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MANUAL OBJECTIVES 

The purpose of this manual is to provide all information necessary to 
interface directly with the I/O device drivers supplied as part of the 
RSX-llM/M-PLUS system. 



INTENDED AUDIENCE 

This manual is intended for use by experienced RSX-llM/M-PLUS 
programmers who want to take advantage of the time and/or space 
savings which result from direct use of the I/O drivers. Readers are 
expected to be familiar with the information contained in the 
RSX-1 IM/M-PLUS Executive Reference Manua l, and to have some experience 
using the Task Builder and either MACRO-11 or FORTRAN programs and to 
be familiar with the manuals describing their use. 

STRUCTURE OF THE DOCUMENT 

Chapter 1 provides an overview of RSX-llM input/output operations. It 
is somewhat tutorial in its approach in introducing the reader to the 
use of logical unit numbers, directive parameter blocks, event flags, 
macro calls, etc. The discussions include the standard I/O functions 
common to a variety of devices, and summarizes standard error and 
status conditions relating to completion of I/O requests. , 

Chapters 2 through 23 describe the use of all device drivers supported 
by RSX-llM and/or RSX-llM-PLUS; refer to the preceding Summary Of 
Technical Changes to determine which drivers are supported in your 
operating system. Descriptions by chapter are as follows: 



Chapter 
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Device Drivers 

Full-duplex terminal communications 
interface 



line 



Half-duplex terminal communications 
interface 



line 



4 
5 
6 
7 
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Virtual terminal driver 

Disks 

DECtape 

DECtape II 

Magnetic tape 
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Chapter Device Drivers 

9 Cassette 

10 Line printers 

11 Card reader 

12 Message-oriented communications line 

interfaces 

13 PCLll parallel communications link 

transmitter and receiver 

14 Analog-to-digital converters 

15 Universal digital controller 

16 Laboratory peripheral systems 

17 Paper tape reader/punch 

18 Industrial control subsystems 

19 The null device 

20 Graphics display terminals 

21 LPAll-K laboratory peripheral accelerator 

22 K-series laboratory peripherals 

23 UNIBUS switch 

Each of these chapters is structured in similar fashion and focuses on 
the following basic elements: 

• Description of the device, including information on physical 
characteristics such as speed, capacity, access, and usage 

• Summary of standard functions supported by the devices and 
descriptions of device-specific functions 

• Discussion of special characters, carriage control codes, and 
functional characteristics, if relevant 

• Summary of error and status conditions returned on acceptance 
or rejection of I/O requests 

• Description of programming hints for users of the device under 
RSX-llM 
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Appendixes A through C provide quick reference material on I/O 
functions and status codes. These include the following: 

Appendix Contents 

A Summary of I/O functions by device 

B I/O function and status codes 

C QIO$ interface to Ancillary Control 

Processors 

ASSOCIATED DOCUMENTS 

Other manuals closely allied to the purposes of this document are 
described briefly in the RSX-llM/RSX-llS Information Directory and the 
RSX-llM-PLUS Information Directory . Each Directory defines the 
intended readership of each manual in the RSX-llM/RSX-llS or 
RSX-llM-PLUS set and provides a brief synopsis of each manual's 
contents. 



CONVENTIONS USED IN THIS MANUAL 

There are a number of conventions and assumptions used in this manual 
to present_ syntax and program coding examples. These are described in 
the following list. 

1. Brackets ([]) in syntactic models enclose optional 
parameters. 

The following example illustrates this format; 
ASTX$S [err] 

2. Braces ({}) in syntactic models indicate that one of the 
Items must be selected, as in the following: 

(DOM I 
CALL< ><inm,icont,idata, [idx] , [isb] , [lun]> 

(domw) 

3. An ellipsis (...) in a syntactic model or coding example 
indicates that parameters have been omitted. As used in this 
manual, an ellipsis in a QIO macro call indicates omission of 
standard QIO parameters described in Section 1.5.1. This is 
illustrated below: 

QIO$C IO.RLV,...,<stadd,size> 

4. Consecutive commas in a coding example indicate null 
arguments. The following illustrates this usage: 

QIO$C IO.ATT,6,,,,AST01 

5. Commas indicating null trailing optional arquments mav be 
omitted, as in the following: 

QIO$C I0.KIL,9. 
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6. Certain parameters are required but ignored by RSX-llM or 
RSX-llM-PLUS; this is necessary to maintain compatibility 
with RSX-llD. For example, in the following, the priority 
specification (fourth parameter) is ignored: 

QIO$C I0.WLB,8. ,EV,,IOSB,ASTX,<IOBUF,NBUF> 

7. With the exception of MACRO-11 coding examples, all numbers 
in the text of this manual are assumed to be decimal; octal 
radix is explicitly declared as in the following: 

An illegal logical block number has been specified 
for DECtape. The number exceeds 577 (1101 octal). 

In MACRO-11 coding examples, all numbers are assumed to be 
octal; decimal radix is explicitly designated by following 
the number with a decimal point, as in the following example: 

QIO$C I0.RDB,14. ,,,IOSB,,<IOBUF,80.> 

8. In FORTRAN subroutine models, parameters which begin with the 
letters i through n indicate integer variables, as in the 
following example: 

CALL DRS (ibuf,ilen,imode, irate, iefn,imask,isb, 
[nbuf] , [istart] , [istop] ) 

In general, where both i and n prefixes are used in a call, 
the i form indicates the name of an array and the n form 
specifies the size of the array. 

All integer arrays and variables are assumed to occupy one 
storage word per variable (that is, INTEGER*2) and all real 
arrays and variables are assumed to occupy two storage words 
per variable (that is, REAL*4) . 
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SOMHARY OF TECHNICAL CHANGES 

This update to the I/O Drivers Reference Manual contains changes and 
additions to document two operating systems: RSX-llM V4.1 and 
RSX-llM-PLUS V2.1. The following list contains a brief summary of 
technical changes for both operating systems: 

• Terminal driver support has been added for the following 
terminals: 

LQP02 

DHVll 

• Disk driver support has been added for the following new disk 
devices: 

UDA50/RA81 

UDA50/RA60 

RC25 

RD51 

RX50 

• Magnetic tape driver support has been added for the TU80 and 
TSV05. 

• Line printer driver support has been added for the following 
printers: 

LNOl 
LP07 
LP26 
LP27 



XXV April 1983 



CHAPTER 1 
RSX-llM/M-PLDS INPOT/ODTPOT 



1.1 OVERVIEW OF RSX-llM I/O 

The RSX-llM/M-PLUS Real-Time Executives support a wide variety of 
PDP-11 input and output devices, including disks, DECtapes, magnetic 
tapes, tape cassettes, line printers, card readers, and such 
laboratory and industrial devices as analog-to-digital converters, 
universal digital controllers, and laboratory peripheral systems. 
Drivers for these devices are supplied by Digital Equipment 
Corporation as part of the system software. This manual describes all 
of the device drivers supported by the system and the characteristics, 
functions, error conditions, and programming hints associated with 
each. Devices not described in this manual can be added to basic 
system configurations, but users must develop and maintain their own 
drivers for these devices. (See the RSX-llM Guide to Writing an I/O 
Driver , including Update No. 1, or the RSX-llM-PLUS Guide to Writing 
an I/O Driver , depending upon the system you are using.) 

Input/output operations under RSX-llM are extremely flexible and are 
as device- and function- independent as possible. Programs issue I/O 
requests to logical units that have been previously associated with 
particular physical device units. Each program or task is able to 
establish its own correspondence between physical device units and 
logical unit numbers (LUNs) . I/O requests are queued as issued; they 
are subsequently processed according to the relative priority of the 
tasks that issued them. I/O requests (for appropriate devices) can be 
issued from tasks by means of either the File Control Services or 
Record Management Services, or can be interfaced directly to an I/O 
driver by means of the Queue I/O (QIO) system directive. 

All of the I/O services described in this manual are requested by the 
user in the form of QIO system directives. A function code included 
in the QIO directive indicates the particular input or output 
operation to be performed. I/O functions can be used to request such 
operations as; 

• Attaching or detaching a physical device unit for a task's 
exclusive use 

• Reading or writing a logical or virtual block of data 

• Cancelling a task's I/O requests 

A wide variety of device-specific input/output operations (for 
example, reading DECtape in^ reverse, rewinding cassette tape) can also 
be specified with QIO directives. 
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1.2 PHYSICAL, LOGICAL, AND VIRTUAL I/O 

There are three possible modes in which an I/O transfer can take 
place: physical, logical, and virtual. 

Physical I/O concerns reading and writing data in the actual physical 
units accepted by the hardware (for example, sectors on a disk). For 
most devices, physical I/O is identical to logical I/O. For example, 
the RK05 disk has sectors of 256 words, the same size as RSX-llM 
logical blocks for all disks. Thus, in this case, a logical block 
maps directly into a physical block. For other devices, the mapping 
is not one to one. The RFll disk, for example, is word addressable; 
however, no physical I/O may be done with the RFll. Data is always 
written in 256-word logical blocks. Another example is the RXOl 
flexible disk. Data for the RXOl is recorded in physical sectors of 
64 words each. Therefore, logical blocks for the RXOl are made up of 
four physical sectors. 

Logical I/O concerns reading and writing data in blocks that are 
convenient for the operating system. In most cases, logical blocks 
map directly into physical blocks. For block-structured devices (for 
example, disks), logical blocks are numbered beginning at 0. For 
non-block-structured devices (for example, terminals) , logical blocks 
are not addressable. 

Virtual I/O concerns reading and writing data to open files. In this 
case, the executive maps virtual blocks into logical blocks. For 

file-structured devices (disks or DECtapes) , virtual blocks are the 

same size as logical blocks and are numbered starting from one (1) and 

are relative to the file rather than to the device. For 

non-file-structured devices, the mapping from virtual block to logical 
block is direct. 



1.3 RSX-llM DEVICES 

The devices listed below are supported by both RSX-llM and 
RSX-llM-PLUS, except as indicated. Drivers are supplied for each of 
these devices, and I/O operations for them are described in detail in 
subsequent chapters of this manual, 

1. A variety of terminals, including the following: 

• ASR/KSR-33 and ASR/KSR-35 Teletypes^ 

• LA12 DECwriter 

• LAIOO DECwriter 

• LA30 DECwriters (serial and parallel) 

• LA34/LA38 DECwriter IV 

• LA36 DECwriter II 

• LA120 DECwriter III 
o LA180S DECprinter 

LQP02 Letter-Quality Printer 



• 



1. Teletype is a registered trademark of the Teletype Corporation. 
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LA50 Personal Printer 

VT05B Alphanumeric Display Terminal 

VT50 Alphanumeric Display Terminal 

VT50H Alphanumeric Display Terminal 

VT52 Alphanumeric Display Terminal 

VT55 Graphics Display Terminal 

VT61 Alphanumeric Display Terminal 

VTlOO Alphanumeric Display Terminal 

VTlOl Alphanumeric Display Terminal 

VT102 Alphanumeric Display Terminal 

VT105 Alphanumeric Display Terminal 

VT125 Alphanumeric Display Terminal 

VT131 Alphanumeric Display Terminal 

VT132 Alphanumeric Display Terminal 

RT02 Data Entry Terminal 

RT02-C Badge Reader and Data Entry Terminal 

These terminals are supported on the following asynchronous 
" ine interfaces : 

DJll Asynchronous Communication Line Interface Multiplexer 

DHll and DHll-DMll-BB Asynchronous Communication Line 
Interface Multiplexer 

DHVll Asynchronous Communications Line Interface 
Multiplexer 

DLll-A, DLll-B, DLll-C, DLll-D, DLll-E and DLll-W 
Asynchronous Communication Line Interfaces 

DLVll-E, DLVll-F Asynchronous Communication Line 
Interfaces 

DZll Asynchronous Communication Line Interface Multiplexer 

variety of disks, including the following: 

ML-11 Fast Electronic Mass Storage Device 

RFll/RSll Fixed-Head Disk 

RS03/RS04 Fixed-Head Disk 

UDA50/RA80/RA81 Fixed-Media Disk 

UDA50/RA60 Pack Disk 

RM80 Fixed-Media Disk 
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RP07 Fixed-Media Disk 

RP11/RP02 or RP03 Pack Disks 

RM02, RM03, RM05 Pack Disk 

RP04, RP05, RP06 Pack Disks 

RK11/RK05 or RK05F Cartridge Disks 

RLll/RLOl or RL02 Cartridge Disk 

RK611/RK06 or RK07 Cartridge Disk 

RC25 Fixed-Media/Removable Cartridge Disk Subsystem 

RD51 Fixed-Media Disk 

RX50 Flexible Disk 

RXll/RXOl Flexible Disk 

RX211/RX02 Flexible Disk 

3. TC11/TU56 DECtape 

4. DL11/TU58 DECtape II 

5. A variety of magnetic tapes including the following: 

• TU80 Magnetic Tape Subsystem 

• TSV05 Magnetic Tape Subsystem 

• TSll Magnetic Tape Subsystem 

• TMll Magnetic Tape Controller with TE10,TU10, or TS03 
Drive 

• RHll/70 Controller with TM02/03 Formatter and TE16, TU16, 
or TU45 Drive 

• RHll/70 Controller with TM03 Formatter and TU77 Drive 

• RH11/RH70 Controller with TM78 Formatter and TU78 Drive 

6. TAll Tape Cassette 

7. A variety of line printers: 

• LPll Controller with LP14, LPOl, LP02, LP04, LP05, LP06, 
LP07, LP26, LP27 Line Printers 

• LSll Controller and Line Printer 

• LVll Controller with LVOl Line Printer 

• LA180 Controller and Line Printer 

• LNOl Laser Printer 

8. CRll Card Reader 
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9. Synchronous and asynchronous line interfaces: 

• DAll-B Asynchronous Communication Line Interface (RSX-llM 
support only) 

• DLll-E Asynchronous Communication Line Interface (RSX-llM 
support only) 

• DLVll-E Asynchronous Communication Line Interface 

• DMCll Synchronous Communication Line Interface 

• DPll Synchronous Communication Line Interface (RSX-llM 
support only) 

• DQll Synchronous Communication Line Interface (RSX-llM 
support only) 

• DUll Synchronous Communication Line Interface (RSX-llM 
support only) 

• DUPll Synchronous Communication Line Interface 
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10. Two analog-to-digital converters: 

• AFCll Analog-to-Digital Converter (RSX-llM support only) 

• ADOl-D Analog-to-Digital Converter (RSX-llM support only) 

11. UDCll Universal Digital Controller (RSX-llM support only) 

12. Laboratory peripheral systems: 

• ARll Laboratory Peripheral System (RSX-llM support only) 

• LPSll Laboratory Peripheral System (RSX-llM support only) 

13. Paper tape devices: 

• PCll Paper Tape Reader/Punch 

• PRll Paper Tape Reader 

14. Industrial control subsystems: 

• ICS/ICR Local and Remote Subsystems (RSX-llM support only) 

• DSS/DRS Digital Input and Output Subsystems (RSX-llM 
support only) 

15. The "Null Device," a software construct that facilitates 
eliminating unwanted output 

16. Two graphics subsystems: 

• VTll Graphics Display System (RSX-llM support only) 

• VS60 Graphics Display System (RSX-llM support only) 

17. Laboratory Peripheral Accelerator: 

• LPAll-K 

18. K-series laboratory peripherals: 

• AAll-K Digital-to-Analog Converter and Display 

• ADll-K Analog-to-Digital Converter 

• AMll-K Multiple-Gain Multiplexer 

• DRll-K Digital I/O Interface 

• KWll-K Programmable Real-Time Clock 

19. PCLll Parallel Communications Link (RSX-llM-PLUS support 
only) 

20. DT07 (RSX-llM-PLUS support only) UNIBUS Switch 

21. Virtual Terminals (RSX-llM-PLUS support only) 

1.4 LOGICAL UNITS 

This section describes the construction of the logical unit table and 
the use of logical unit numbers. 
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1.4.1 Logical Unit Number 

A logical unit number, or LUN, is a number associated with a physical 
device unit during RSX-llM/M-PLUS I/O operations. For example, LUN 1 
might be associated with one of the terminals in the system, LUNs 2, 
3, 4, and 5 with DECtape drives, and LUNs 6, 7, and 8 with disk units. 
The association is a dynamic one; each task running in the system can 
establish its own correspondence between LUNs and physical device 
units, and can change any LUN/physical-device-unit association at 
almost any time. The flexibility of this association contributes 
heavily to system device independence. 

A logical unit number is simply a short name used to represent_ a 
logical-unit/physical-device-unit association. Once the association 
has been made, the LUN provides a direct and efficient mapping to the 
physical device unit, and eliminates the necessity to searchthe 
device tables whenever the system encounters a reference to a physical 
device unit. 

The user should remember that, although a LUN/physical-device-unit 
association can be changed at any time, reassignment of a LUN at run 
time causes pending I/O requests for the previous LUN assignment to be 
cancelled. It is the user's responsibility to verify that all 
outstanding I/O requests for a LUN have been serviced before that LUN 
is associated with another physical device unit. 



1.4.2 Logical Unit Table 

There is one Logical Unit Table (LUT) for each task running in a 
system. This table is a variable-length block contained in the task 
header. Each LUT contains sufficient 2-word entries for the number of 
logical units specified by the user at task-build time by the "UNITS-" 
option. 



Each entry or slot contains a pointer 
currently associated with that LUN. 
request, the system matches the appropr 
the LUN specified in the call by inde 
supplied as the LUN. Thus, if the call 
system accesses the sixth 2-word entr 
I/O request with the physical device un 
The number of LUN assignments valid f 
but cannot be greater than the number o 
time. 



to the physical device unit 
Whenever a user issues an I/O 
iate physical device unit to 
xing into the LUT by the number 
specifies 6 as the LUN, the 
y in the LUT and associates the 
it to which the entry points. 
or a task ranges from to 255, 
f LUNs specified at task-build 



Figure 1-1 illustrates a typical Logical Unit Table. 
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Figure 1-1 Logical Unit Table 
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Word 1 of each active (assigned) 2-word entry in the logical unit 
table points to the Unit Control Block (UCB) of the physical device 
unit with which the LUN is associated. This linkage may be indirect; 
that is, the user may force redirection of references from one unit to 
another unit with the MCR command REDIRECT. Word 2 of each entry is 
reserved for mountable devices. 



1.4.3 Changing LUN Assignments 

Logical unit numbers have no significance until they are associated 
with a physical device unit by means of one of the methods described 
below: 

1. At task-build time, the user can specify an ASG keyword 
option, which associates a physical device unit with a 
logical unit number referenced in the task being built. 

2. The user or system operator can issue a REASSIGN command to 
MCR; this command reassigns a LUN to another physical device 
unit and thus changes the LUN-physical device unit 
correspondence. Note that this reassignment has no effect on 
the in-core image of a task. 

3. At run time, a task can dynamically change a LUN assignment 
by issuing the Assign LUN system directive, which changes the 
association of a LUN with a physical device unit during task 
execution. 



1.5 ISSUING AN I/O REQUEST 

User tasks perform I/O in the RSX-llM/M-PLUS system by submitting 
requests for I/O service in the form of QIC or QIO And Wait system 
directives. See the RSX-llM/M-PLUS Executive Reference Manual for a 
complete description of system directives. 

In RSX-llM/M-PLUS, as in most multiprogramming systems, tasks do not 
normally access physical device units directly. Instead, they utilize 
input/output services provided by the Executive, since it can 
effectively multiplex the use of physical device units over many 
users. The Executive routes I/O requests to the appropriate device 
driver and queues them according to the priority of the requesting 
task. I/O operations proceed concurrently with other activities in an 
RSX-llM/M-PLUS system. 

Before a request is queued, it must pass a battery of acceptance tests 
administered by the Executive. If the request fails, it is rejected; 
this rejection is signalled by the setting of the C-bit when the 
statement following the QIO is executed. It is good programming 
practice to check for directive rejection by following the QIO 
directive with a BCS instruction. 

After an I/O request has been queued, the system does not wait for the 
operation to complete. If at any time the user task that issued the 
QIO request cannot proceed until the I/O operation has completed, it 
should specify an event flag (see Sections 1.5.1 and 1.5.2) in the QIO 
request and should issue a Waitfor system directive specifying the 
same event flag at the point where synchronization must occur. The 
task then waits for completion of I/O by waiting for the specified 
event flag to be set. 
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The QIOW directive, QIO And Wait, is a more economical way to achieve 
this synchronization. QIOW automatically waits until I/O has 
completed before returning control to the task. Thus, the additional 
Waitfor directive is not necessary. 

Each QIO or QIOW directive must supply sufficient information to 
identify and queue the I/O request. The user may also want to include 
locations to receive error or status codes and to specify the address 
of an asynchronous system trap service routine. Certain types of I/O 
operations require the specification of device-dependent information 
as well. Typical QIO parameters are the following: 

I/O function to be performed 

Logical unit number associated with the physical device unit 
to be accessed 

Optional event flag number for synchronizing I/O completion 
processing (required for QIOW) 

Optional address of the I/O status block to which information 
indicating successful or unsuccessful completion is returned 

Optional address of an asynchronous system trap service 
routine to be entered on completion of the I/O request 

Optional device- and function-dependent parameters specifying 
such items as the starting address of a data buffer, the size 
of the buffer, and a block number 

A set of system macros that facilitate the issuing of QIO directives 
is supplied with the RSX-llM/M-PLUS system. These macros, which 
reside in the System Macro Library (LB : [1 , 1] RSXMAC.SML) , must be made 
available to the source program by means of the MACRO-11 Assembler 
directive .MCALL. The function of .MCALL is described in Section 
1.7.3. Several of the first six parameters in the QIO directive are 
optional, but space for these parameters must be reserved. 

During expansion of a QIO macro, a value of is defaulted for all 
null (omitted) parameters. Inclusion of the device- and 
function-dependent parameters depends on the physical device unit and 
function specified. If the user wanted to specify only an I/O 
function code, a LUN, and an address for an asynchronous system trap 
service routine, the following might be issued; 

QIOSC I0.ATT,6, ,, ,ASTOX 



10. ATT 

The I/O function code for attach, 

6 

The LUN. 

ASTOX 



The AST address. 
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Null arguments for the event flag number, the request priority 
and the address of the I/O status block. 

No additional device- or function-dependent parameters are required 
for an attach function. The C form of the QIO$ macro is used here and 
in most of the examples included in Chapter 1. Section 1.7 describes 
tne three legal forms of the macro. 

For convenience, any comma may be omitted if no parameters appear to 
the right of it. The command above could therefore be issued as 
tollows, if the asynchronous system trap was not desired: 

QIO$C 10. ATT, 6 

All extra commas have been dropped. If, however, a parameter appears 
to the right of any place-holding coro.ma, that comma must be retained. 



1.5.1 QIC Macro Format 

The arguments for a specific QIO macro call may be different for each 
I/O device accessed and for each I/O function requested. The general 
format of the call is, however, common to all devices and is as 
follows : 

QIO$C fnc,lun,[efn] ,[pri] ,[isb] , [ast] [ ,<pl,p2, . . . ,p6>] 

where brackets ([]) enclose optional or function-dependent parameters. 
If function-dependent parameters <pl,...,p6> are required, these 
parameters must be enclosed within angle brackets (<>). The followinq 
paragraphs summarize the use of each QIO parameter. Section 1.7 
discusses different forms of the QIO$ macro itself. 

The fnc parameter is a symbolic name representing the I/O function to 
be performed. This name is of the form 

10. XXX 



XXX 

Identifies the particular I/O operation. 

For example, a QIO request to attach the physical device unit 
associated with a LUN specifies the function code 

10. ATT 

A QIO request to cancel (or kill) all I/O requests for a specified LUN 
begins in the following way: 

QIO$C lO.KIL,... 

The fnc parameter specified in the QIO request is stored internally as 
a function code in the high-order byte and modifier bits in the 
low-order byte of a single word. The function code is in the range 
^r^K"?- ^^ ^""^ IS a binary value supplied by the system to match the 
symbolic name specified in the QIO request. The corresoondence 
oetween global symbolic names and function codes is defined' in the 
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system object module library, which is automatically searched by the 
Task Builder. Local symbolic definitions may also be obtained by the 
FILIO$ and SPCIOS macros, which reside in the System Macro Library and 
are summarized in Appendix A. Several similar functions may have 
identical function codes, and may be distinguished only by their 
modifier bits. For example, the DECtape read logical forward and read 
logical reverse functions have the same function code. Only the 
modifier bits for these two operations are stored differently. 

The lun parameter represents the logical unit number (LUN) of the 
associated physical device unit to be accessed by the I/O request. 
The association between the physical device unit and the LUN is 
specific to the task that issues the I/O request, and the LUN 
reference is usually device independent. An attach request to the 
physical device unit associated with LUN 14 begins in the following 
way: 

QIO$C I0.ATT,14. , . . . 

Because each task has its own LUT in which the physical device 
unit-LUN correspondences are established, the legality of a LUN 
parameter is specific to the task that includes this parameter in a 
QIO request. In general, the LUN must be in the following range: 

<LUN <length of task's LUT (if nonzero) 

The number of LUNs specified in the LUT of a particular task cannot 
exceed 255. 

The efn parameter is a number representing the event flag to be 
associated with the I/O operation. It may optionally be included in a 
QIO or QIO And Wait request. The specified event flag is cleared when 
the I/O request is queued and is set when the I/O operation has 
completed. If the task has issued the QIO And Wait directive, 
execution is automatically suspended until the I/O completes. If a 
010 directive has been issued (with no Waitfor directive), then task 
execution proceeds in parallel with the I/O. When the task continues 
to execute, it may test the event flag whenever it chooses by using 
the Read All Event Flags system directive (if group global event flags 
are not being used) or the Read Extended Flags system directive (for 
all event flags, including group-global event flags). If the user- 
specifies an event flag number, this number must be m the range l 
through 96. If an event flag specification is not desired, efn can be 
omitted or can be supplied with a value of 0. Event flags 1 through 
32 are local (specific to the issuing task); event flags 33 through 
64 are global (shared bv all tasks in the system). Event flags 65 
through 96 are group-global event flags (shared by all tasks in the 
same user group) . Flags 25 through 32 and 57 through 64 are reserved 
for use by system software. Within these bounds, the user can specify 
event flags as desired to synchronize I/O completion and_ task 
execution. Section 1.5.2 provides a more detailed explanation of 
event flags and significant events. 

NOTE 

If an event flag is not specified, the 
Executive treats the directive as if it 
were a simple QIO request. 
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The optional pri parameter is supplied only to make RSX-llM/M-PLUS QIO 
requests compatible with RSX-llD. An RSX-llM I/O request 
automatically assumes the priority of the requesting task. Thus, it 
is recommended that a value of (or a null) be used for this 
parameter. 

The optional isb parameter identifies the address of the I/O status 
block (I/O status double-word) associated with the I/O request. This 
block is a 2-word array in which a code representing the final status 
of the I/O request is returned on completion of the operation. This 
code is a binary value that corresponds to a symbolic name of the form 
IS. XXX (for successful returns) or lE.xxx (for error returns) . The 
binary error code is returned to the low-order byte of the first word 
of the status block. It can be tested symbolically, by name. For 
example, the symbolic status IE, BAD is returned if a bad parameter is 
encountered. The following illustrates the examination of the I/O 
status block, lOST, to determine if a bad parameter has been detected: 

QIO$C I0.ATT,14. ,2,,I0ST 
BCS DIRERR 
WTSE$C 2 



CMPB #IS.SUC,IOST 
BNE ERROR 

The correspondence between global symbolic names and I/O completion 
codes is defined in the system object module library, which is 
automatically searched by TKB. Local symbolic definitions, which are 
summarized in Appendix B, may also be obtained by the IOERR$ macro, 
which resides in the System Macro Library. 

Certain device-dependent information is returned to the high-order 
byte of the first word of isb on completion of the I/O operation. If 
a read or write operation is successful, the second word is also 
significant. For example, in the case of a read function on a 
terminal, the number of bytes typed before a carriage return is 
returned in the second word of isb. If a magtape unit is the device 
and a write function is specified, this number represents the number 
of bytes actually transferred. The status block can be omitted from a 
QIO request if the user does not intend to test for successful 
completion of the request. 

The optional ast parameter specifies the address of a service routine 
to be entered when an asynchronous system trap occurs. Section 1.5.3 
discusses the use of asynchronous system traps, and Section 2.2.5 of 
the RSX-llM/M-PLUS Executive Reference Manual describes traps in 
detail. If the user wants to interrupt his task to execute special 
code on completion of an I/O request, an asynchronous system trap 
routine can be specified in the QIO request. When the specified I/O 
operation completes, control branches to this routine at the software 
priority of the requesting task. The asynchronous code beginning at 
address ast is then executed, much as an interrupt service routine 
would be. If the user does not want to perform asynchronous 
processing, the ast parameter can be omitted or a value of specified 
in the QIO macro call. 

The additional QIO parameters, <pl,p2, . . . ,p6>, are dependent on the 
particular function and device specified in the I/O request. Typical 
parameters may include I/O buffer address, I/O buffer length, and so 
forth. Between zero and six parameters can be included, depending on 
the particular I/O function. Rules for including these parameters and 
legal values are described in subsequent chapters of this manual. 
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1.5.2 Significant Events 

"Significant event" is a term used in real-time systems to indicate a 
change in system status. In RSX-llM/M-PLUS, a significant event is 
declared when an I/O operation completes. This signals the system 
that a change in status has occurred and indicates that the Executive 
should review the eligibility of all tasks in the system to determine 
which task should run next. The use of significant events helps 
cooperating tasks in a real-time system to communicate with each 
other, and thus allows these tasks to control their own sequence of 
execution dynamically. 

Significant events are normally set by system directives, either 
directly or indirectly, by completion of a specified function. Event 
flags associated with tasks may be used to indicate which significant 
event has occurred. Of the 96 event flags available in 
RSX-llM/M-PLUS, the flags numbered 1 through 32 are local to an 
individual task and are set or reset only as a result of that task's 
operation. The event flags numbered 33 through 64 are common to all 
tasks. Flags 25 through 32 and 57 through 64 are reserved for system 
software use. The event flags numbered 65 through 96 are group-global 
event flags, which are common to all tasks running under the same user 
group. 

An example of the use of significant events follows. A task issues a 
QIO directive with an efn parameter specified. A Waitfor directive 
follows the QIO and specifies as an argument the same event flag 
number. The event flag is cleared when the I/O request ' queued by 
the Executive, and the task is blocked when it executes the Waitfor 
directive until the event flag is set and a significant event is 
declared at the completion of the I/O request. The task resumes when 
the appropriate event flag is set, and execution resumes at the 
instruction following the Waitfor directive. During the time that the 
task is blocked, other tasks have a chance to run, thus increasing 
throughput in the system. 



1.5.3 System Traps 

System traps are used to interrupt task execution and to cause a 
transfer of control to another memory location for special processing. 
Traps are handled by the Executive and are relevant only to the task 
in which they occur. To use a system trap, a task must contain a trap 
service routine, which is automatically entered when the trap occurs. 

There are two types of system traps: synchronous and asynchronous. 
Both are used to handle error or event conditions, but the two traps 
differ in their relation to the task that is running when they are 
detected. Synchronous traps signal error conditions within the 
executing task. If the same instruction sequence were repeated, the 
same synchronous trap would occur at the same place in the task. 
Asynchronous traps signal the completion of an external event such as 
an I/O operation. An asynchronous system trap (AST) usually occurs as 
the result of initiating or completing an external event rather than a 
program condition. 

The Executive queues ASTs in a first-in-first-out queue for each task 
and monitors all asynchronous service routine operations. Because 
asynchronous traps may be the end result of I/0-related activity, they 
cannot be controlled directly by the task that receives them. 
However, the task may, under certain circumstances, block recognition 
of ASTs to prevent simultaneous access to a critical data region. 
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When access to the critical data region has been completed, the queued 
ASTs may again be honored. The DSAR$S (Disable AST Recognition) and 
ENAR$S (Enable AST Recognition) system directives provide the 
mechanism for accomplishing this. An example of an asynchronous trap 
condition is the completion of an I/O request. The timing of such an 
operation clearly cannot be predicted by the requesting task. If an 
AST service routine is not specified in an I/O request, a trap does 
not occur and normal task execution continues. 

Asynchronous system traps associated with I/O requests enable the 
requesting task to be truly event driven. The AST service routine 
contained in the initiating task is executed as soon as possible, 
consistent with the task's priority. Using the AST routine to service 
I/0-related events provides a response time that is considerably 
better than a polling mechanism, and provides for better overlap 
processing than the simple QIO and Waitfor sequence. Asynchronous 
system traps also provide an ideal mechanism for use in multiple 
buffering of I/O operations. 

All ASTs are inserted in a first-in-first-out queue on a per task 
basis as they occur (that is, the event that they are to signal has 
expired). They are effected one at a time whenever the task does not 
have ASTs disabled and is not already in the process of executing an 
AST service routine. The process of effecting an AST involves storing 
certain information on the task's stack, including the task's Waitfor 
mask word and address, the Directive Status Word (DSW) , the PS, the PC 
and any trap dependent parameters. The task's general-purpose 
registers R0-R5 are not saved, and thus it is the responsibility of 
the AST service routine to save and restore the registers it uses. 
After an AST is processed, the trap-dependent parameters (if any) must 
be removed from the task's stack and an AST Service Exit directive 
executed. The ASTXSS macro described in Section 1,7.6 of this manual 
is used to issue the AST Service Exit directive. On AST service exit, 
control is returned to another queued AST, to the executing task, or 
to another task that has been waiting to run. The RSX-llM/M-PLUS 
Executive Reference Manual describes in detail the purpose of AST 
service routines and all system directives used to handle them. 



1.6 DIRECTIVE PARAMETER BLOCKS 

A Directive Parameter Block (DPB) is a fixed-length area of contiguous 
memory that contains the arguments specified in a system directive 
macro call. The DPB for a QIO directive has a length of 12 words. It 
is generated as the result of expanding a QIO macro call. The first 
byte of the DPB contains the directive identification code (DIG) 
— always 1 for QIO. The second byte contains the size of the DPB in 
words — always 12 for RSX-llM/M-PLUS. During assembly of a user task 
containing QIO requests, the MACRO-11 Assembler generates a DPB for 
each I/O request specified in a QIO macro call. At run" time, the 
Executive uses the arguments stored in each DPB to create, for each 
request, an I/O packet in system dynamic storage. The packet is 
entered by priority into a queue of I/O requests for the specified 
physical device unit. This queue is created and maintained by the 
Executive and is ordered by the priority of the tasks that issued the 
requests. The I/O drivers examine their respective queues for the I/O 
request with the highest priority capable of being executed. This 
request is dequeued (removed from the queue) and the I/O operation is 
performed = The process is then repeated until the queue is emptied of 
all requests. 
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After the I/O request has been completed, the Executive declares a 
significant event and may set an event flag, cause a branch to an 
asynchronous system trap service routine, and/or return the I/O 
status, depending on the arguments specified in the original QIO macro 
call. Figure 1-2 illustrates the layout of a sample DPB. 



WORD SIZE OF DPB 
1 
2 

3 PRIORITY 
4 
5 



11 



1 





12 


1 


FNC 


MODIFIERS 




LUN 


PRI 


EFN 


ISB 


AST 


DEVICE- 
DEPENDENT 
PARAMETERS 



BYTE 

DIG FOR QIO 
DIRECTIVE 

I/O FUNCTION 
LOGICAL UNIT NUMBER 

EVENT FLAG NUMBER 

ADDRESS OF I/O 
STATUS BLOCK 

ADDRESS OF 
ASYNCHRONOUS TRAP 
SERVICE ROUTINE 



Figure 1-2 QIO Directive Parameter Block 



1.7 I/0-RELATED MACROS 

Several system macros are supplied with the RSX-llM/M-PLUS system to 
issue and return information about I/O requests. These macros reside 
in the System Macro Library and must be made available during assembly 
by the MACRO-11 assembler directive .MCALL. 

Also supplied are FORTRAN-callable subroutines that perform the same 
functions as the system macros. See the RSX-llM/M-PLUS Executive 
Reference Manual for details. 

There are three distinct forms of most of the system directive macros 
discussed in this section. The following list summarizes the forms of 
QIO$, but the characteristics of each form also apply to QIOW$, AHJN$, 
GLUN$, and other system directive macros described below. 

1. QIO$ generates a directive parameter block for the I/O 
request at assembly time, but does not provide the 
instructions necessary to execute the request. This form of 
the request is actually executed using the DIR$ macro. It is 
useful if the DPB is to be used in several different places 
in the task and/or modified or referenced by the task at run 
time. 
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2. QIO$S generates a directive parameter block for the I/O 
request on the stack, and also generates code to execute the 
request. This is a useful form for reentrant, shareable code 
since the DPB is generated dynamically at execution time. 

3. QIO$C generates a directive parameter block for the I/O 
request at assembly time, and also generates code to execute 
the request. The DPB is generated in a separate program 
section called $DPB$$. This approach incurs little system 
overhead and is useful when an I/O request is executed from 
only one place in the program. 

Parameters for both the QIO$ and QIO$C forms of the macro must be 
valid expressions to be used in assembler data-generating directives 
such as .WORD and .BYTE. Parameters for the QIOSS form must be valid 
source operand address expressions to be used in assembler 
instructions such as MOV and MOVB. The following example references 
the same parameters in the three distinct forms of the macro call. 

QIO$ IO.RLB,6,2, , ,AST01 , <RDBUF, 80 . > 

QIO$C IO.RLB,6,2, , , ASTOl , <RDBUF, 80 . > 

QIO$S #IO.RLB,#6,#2,,,#AST01,<#RDBUF,#80.> 

Only the QIO$S form of the macro produces the DPB dynamically. The 

other two forms generate the DPB at assembly time. The 

characteristics and use of these different forms are described in 
greater detail in the RSX-llM/M-PLUS Executive Reference Manual . 

The following Executive directives and assembler macros are described 
in this section: 

1. QIO$, which is used to request an I/O operation and supply 
parameters for that request 

2. QIOW$, which is equivalent to QIOS followed by WTSE$ 

3. DIRS, which specifies the address of a directive parameter 
block as its argument, and generates code to execute the 
directive 

4. .MCALL, which is used to make available from the System Macro 
Library all macros referenced during task assembly 

5. ALUNS, which is used to associate a logical unit number with 
a physical device unit at run time 

6. GLUN$, which requests that the information about a physical 
device unit associated with a specified LUN be returned to a 
user-specified buffer 

7. ASTX$S, which is used to terminate execution of an 
asynchronous system trap (AST) service routine 

8. WTSE$, which instructs the system to block execution of the 
issuing task until a specified event flag is set 
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1.7.1 The QIO$ Macro; Issuing an I/O Request 
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10. RLE, 6, 2, , ,AST01,<BUFFER,80.> 

; CREATE QIO DPB 



READl; 



DIR$ 



#QIOREF 



ISSUE I/O REQUEST 



READ2: 



DIR$ 



#QIOREF 



ISSUE I/O REQUEST 



1.7.2 The QIOW$ Macro: Issuing an I/O Request and Waiting for an 
Event Flag 

The QIOW$ macro is equivalent to a QIO$ followed by a WTSE$. It is 
more economical to issue a QIO And Wait request than to use the two 
separate macros. An event flag (efn parameter) must be specified with 
QIOW$. 



1-7.3 The DIR$ Macro: Executing a Directive 

The DIR$ (execute directive) macro has been 
task to reference a previously defined DPB. 



implemented to allow a 
It is issued in the form: 



DIR$ 



[addr] [ ,err] 



addr 



err 



The address of a directive parameter block to be used in the 
directive. If addr is not included, the DPB itself or the 
address of the DPB is assumed to already be on the stack. This 
parameter must be a valid source operand for a MOV instruction 
generated by the DIR$ macro. 



An optional argument which specifies the address of an error 
routine to which control branches if the directive is rejected. 
The branch occurs by means of a JSR PC, err if the C-bit is set, 
indicating rejection of the QIO directive. 
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1.7.4 The .MCALL Directive: Retrieving System Macros 

.MCALL is a MACRO-11 Assembler directive that retrieves macros from 
the System Macro Library (LB : [1, 1] RSXMAC.SML) for use during assembly. 
It must be included in every user task invoking system macros. .MCALL 
is usually placed at the beginning of a user-task source module and 
specifies, as arguments in the call, all system macros that must be 
made available from the library. 

The following example illustrates the use of this directive: 

.MCALL QIO$,QIO$S,DIR$,WTSE$S ; MAKE MACROS AVAILABLE 



ATTACH: QIO$S #10. ATT, #6 , , , lOSB , #AST02 ; ATTACH DEVICE 



QIOREF: QIO$ 



READl: DIR$ 



I0.RLB,6,, ,IOSB,AST01,. . . ; CREATE ONLY QIC DPB 



#QIOREF,DIRERR 



; ISSUE I/O REQUEST 



As many macro references as can fit on a line can be included in a 
single .MCALL directive. There is no limit to the number of .MCALL 
directives that can be specified. 



1.7.5 The ALUN$ Macro: Assigning a LUN 

The Assign LUN macro is used to associate a logical unit number with a 
physical device unit at run time. All three forms of the macro call 
may be used. Assign LUN does not request I/O for the physical device 
unit, nor does it attach the unit for exclusive use by the issuing 
task. It simply establishes a LUN-physical device unit relationship, 
so that when the task requests I/O for that particular LUN, the 
associated physical device unit is referenced. The macro is issued 
from a MACRO-11 program in the following way: 



lun 



dev 



unt 



ALUN$ lun, dev, unt 



The logical unit number to be associated with the specified 
physical device unit. 



The device name of the physical device or a logical device name 
assigned to a physical device (see MCR ASN command) . 



The unit number of that device specified above. 
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For example, to associate LUN 10 with terminal unit 2, the following 
macro call could be issued by the task: 

ALUN$C 10.,TT,2 

A unit number of represents unit for multiunit devices such as 
disk, DECtape, or terminals; it indicates the single available unit 
for devices without multiple units, such as card readers and line 
printers. 

Logical devices are SYSGEN options that allow the user to assign 
logical names to physical devices by means of the MCR command ASN. 
See the RSX-llM/M-PLUS MCR Operations Manual for a full description. 

The example included below illustrates the use of the three forms of 
the ALUN$ macro. 



DATA DEFINITIONS 



ASSIGN: ALUN$ 10.,TT,2 



GENERATE DPB 



EXECUTABLE SECTION 



DIR$ 



#ASSIGN 



; EXECUTE DIRECTIVE 



ALUN$C 10.,TT,2 



GENERATE DPB IN SEPARATE PROGRAM 
SECTION, THEN GENERATE CODE TO 
EXECUTE THE DIRECTIVE 



ALUN$S #10.,#"TI,#0 ; GENERATE DPB ON STACK, THEN 

; EXECUTE DIRECTIVE 



1.7.5.1 Physical Device Names - The following list contains physical 
device names, listed alphabetically, that may be included as dev 
parameters: 



Name 



Device 



AD 



ADOl-D Analog-to-Digital Converter (not supported 
RSX-llM-PLUS systems) 



in 



AF 



AFCll Analog-to-Digital Converter (not supported in 
RSX-llM-PLUS systems) 



AR 



ARll Laboratory Peripheral System (not supported in 
RSX-llM-PLUS systems) 
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Name Device 

BS DT03/DT07 UNIBUS Switch (supported in RSX-llM-PLUS 
systems only) 

CD CDll Card Reader 

CP Central Processor Unit (CPU) in a multiprocessor 
system (supported in RSX-llM-PLUS systems only) 

CR CRll/CMll Card Reader 

CT TA11/TU60 Tape Cassette 

DB RP04, RP05, RP06 Pack Disk 

DD TU58 DECtape II 

DF RFll/RSll Fixed-Head Disk 

DK RK11/RK05 Cartridge Disk 

DL RL11/RL01/RL02 Cartridge Disk 

DM RK611/RK06 and RK711/RK07 Cartridge Disk 

DP RP11/RP02/RP03 Pack Disk 

DR RM02/RM03/RM05 Pack Disk and RM80/RP07 Fixed-Media 
Disk 

DS RS03 and RS04 Fixed-Head Disks 

DT TC11/TU56 DECtape 

DU RA80/RA81 Fixed-Media Disk, RA60 Pack Disk, RC25 Disk 
Subsystem, RD51 Fixed-Media Disk, and RX50 Flexible 
Disk 

DX RXll/RXOl Flexible Disk 

DY RX211/RX02 Flexible Disk 

EM ML-11 Fast Electronic Mass Storage Device 

GR VT11/VS60 Graphics Systems (not supported in 
RSX-llM-PLUS systems) 

IC ICS/ICR Industrial Control Local and Remote Subsystems 
(not supported in RSX-llM-PLUS systems) 

IS DSS/DRS Digital Input and Output Subsystems (not 
supported in RSX-llM-PLUS systems) 

LA LPAll-K Laboratory Peripheral Accelerator 

LP LA180/LP11/LS11/LV11 Line Printers and LNOl Laser 

Printer 

LS LPSll Laboratory Peripheral System (not supported in 
RSX-llM-PLUS systems) 
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Name Device 

MF TU78 Magnetic Tape 

MM TUL6/TE16/TU45/TU77/TM02/TM03 Magnetic Tape 

MS TSll, TU80, or TSV05 Magnetic Tape 

MT TMll/TUlO/TUll or TS03 Magnetic Tape 

NL The Null Device 

PP PCll Paper Tape Punch 

PR PCll or PRll Paper Tape Reader 

LR PCLll-A/PCLll-B Receiver Port (supported in 
RSX-llM-PLUS systems only) 

TT Terminals (regardless of interface) 

LT PCLll-A/PCLll-B Transmitter Port (supported in 
RSX-llM-PLUS systems only) 

UD UDCll Universal Digital Controller (not supported in 
RSX-llM-PLUS systems) 

XB DAll-B Parallel Unibus Link (not supported in 
RSX-llM-PLUS systems) 

XL DLll-E Asynchronous Communication Line Interface (not 
supported in RSX-llM-PLUS systems) 

XM DMCll Synchronous Communication Line Interface 

XP DPll Synchronous Communication Line Interface (not 
supported in RSX-llM-PLUS systems) 

XQ DQll Synchronous Communication Line Interface (not 
supported in RSX-llM-PLUS systems) 

XU DUll Synchronous Communication Line Interface (not 
supported in RSX-llM-PLUS systems) 

XW DUPll Synchronous Communication Line Interface 

YH DHll or DHVll Asynchronous Communications Line 
Multiplexer 

YL DLll-A/DLll-B/DLll-C/DLll-D/DLll-E Asynchronous 
Communications Line Interface (DLll-B, DLll-E, DPll, 
DQll, and DUll are not supported in RSX-llM-PLUS 
systems) 

YZ DZll Asynchronous Communications Line Multiplexer 

ZA-ZZ Reserved for customer use (not used by DIGITAL) 
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1.7.5.2 Pseudo-Device Names - A pseudo-device is a logical device 
that can normally be redirected by the operator to ano?her physical 
device unit at any time, without requiring changes in programs tMt 
reference the pseudo-device. Dynamic redirection of a physicaTdevice 
S2r IeSign'' T'^' ^" the system; reassignment by 'mLns of 'Jhl 
MCR REASSIGN command affects only one task. The followina 
pseudo-devices are supported, as indicated: toiiowing 

^<'*^« Device 

CL Console listing, normally the line printer. 

CO Console output, normally the main operator's console. 

HT Network remote terminal 

LB System library device, normally the device from which 

the system was bootstrapped. For example, LB: is the 

device that tasks such as TKB and MAC access for 
default library files. 

NL Null device. 

NS Network pseudo-device for NSP. 

NX Network pseudo-device for DLX. 

On-line reconfiguration pseudo-device (RSX-llM-PLUS 
only) . 



RD 



^P Spooling scratch disk device. 



SY user default device. On nonmultiuser systems, SY- is 
normally the disk from which the system was 
bootstrapped. On multiuser systems, SY: is normally 
Che default login device. 

VD Virtual Device. 

TI Pseudo- input terminal; TIO: is the terminal from 
which a task was requested. 

The pseudo-device Tl cannot be redirected, since such 
redirection would have to be handled on a per-task 
rather than a system-wide basis (that is, change the TI 
device for one task without affecting the TI 
assignments for other tasks) . 

Virtual terminal. Used by some RSX-llM-PLUS offspring 

pIv fiM^n.Mo' ^°^ command and data I/O. (Supported in 
RSX-llM-PLUS systems only) . 



VT 



1.7.6 The GLUN$ Macro: Retrieving LDN Information 

?™ ShL^"^i ^"f°^"'^tion macro requests that information about a 
specified Si thfl^: -""'l f-ciation be returned in a 6-word buffer 
H?^^if^ ^ issuing task. Upon successful completion of the 
directive processing, the buffer contains the information listed in 
tSe mi^iA fPP'^^P'^i^te for the specific device. All three forms of 
the' folloeinriayf^ '^ ^'''' " '^ ^^^"^^ '^"^ ^ "^^^^"^^ P-^-- - 
GLUN$ lun,buf 
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The logical unit number associated with the physical device unit 
for which information is requested. 



The 6-word buffer to which information is returned. 



For example, to request information on the disk unit associated with 
LUN 8, the following call is issued: 

GLUN$C 8.,I0BUF 



Table 1-1 
Get LUN Inform.ation 



Numerical Offset 



Word 



Byte 



Bit 



Word 



Symbolic Offset 



G.LONA 



G.LUCWI 
(O.CWl) 



Byte 



G.LONU 
G.LUFB 



Bit 



Contents 



(DV.REC) 

(DV.CCL) 

(DV.TTY) 
(DV.DIR) 

(DV.SDI) 

(DV.SQD) 
(DV.MSD) 



Name of device associated with 
LON (ASCII bytes) 

Unit number of associated device 

Driver flag value. Returned as 
200 octal if the driver is 
resident, or as if a loadable 
driver is not in the system 



First 
word : 



device 



characteristics 



Unit record-oriented device (for 
example, card reader, line 
printer) (1 = yes) 

Carriage-control device (for 
example, line printer, terminal) 
(1 = yes) 

Terminal device (1 = yes) 

Directory device (for example, 
DECtape, disk) (1 = yes) 

Single directory device (for 
example, ANSI-standard magtape) 
(1 = yes) 

Sequential device (for example, 
ANSI-standard magtape) (1 = yes) 

Mass storage device (for example, 
disks and tapes) (1 = yes) 



1. The following word and bit symbols shown in parentheses are symbols used in 
defining and referencing corresponding items in the device DCB, 

(continued on next page) 
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Table 1-1 (Cont.) 
Get LUN Information 



Numerical Offset 



Word 



Byte 



Bit 



10 
11 
12 
13 

14 

15 



Word 



Symbolic Offset 



G.LUCW+02 

(U.CW2) 
G.LDCW+04 

(D.CW3) 
G.LUCW+06 

(0.CW4) 



Byte 



Bit 



(02. XXX) 



(DV.DMD) 

(DV.EXT) 

(DV.SWL) 

(DV.ISP) 
(DV.OSP) 
(DV.PSE) 
(DV.COM) 

(DV.Fll) 
(DV.MNT) 



(03. XXX) 



Contents 



User-mode diagnostics supported 
(1 = yes) 

Device supports 22-bit direct 
addressing 



Unit software 
(1 = yes) 



write-locked 



Input spooled device (1 = yes) 

Output spooled device (1 = yes) 

Pseudo-device (1 = yes) 

Device mountable as a 
communications channel for 
Digital network support (for 
example, DPll, Dull) (1 = yes) 

Device mountable as a FILES-11 
device (for example, disk or 
DECtape) (1 = yes) 

Device mountable (logical OR of 
bits 13 and 14) (1 = yes) 



Second 
word : 



device characteristics 



Device-specific information 

Third device characteristics 
word: 

Device-specific information^ 

Fourth device characteristics 
word: 

Default buffer size (for example, 
for disks, and line length for 
terminals) . 



2. For mass storage devices, such as disks, DECtape, and DECtape II, this is 
the number of blocks (maximum logical block number plus one) . For the prooer 
r'fn^Ll'*: RX211/RX02 flexible disk, it is important to be able to"^ test 
G.LuCW+4 to determine the medaa density. 



1-23 



April 1983 



RSX-llM/M-PLUS INPDT/OOTPDT 

The example included below illustrates the use of the three forms of 
the GLUN$ macro. 



DATA DEFINITIONS 



GETLUN: GLUN$ 6,DSKB0F 



; GENERATE DPB 



EXECUTABLE SECTION 



DIR$ #GETLUN 



EXECUTE DIRECTIVE 



GLUN$C 6,DSKBUF 



GLUN$S #6,#DSKBUF 



GENERATE DPB IN SEPARATE PROGRAM 
SECTION, THEN GENERATE CODE TO 
EXECUTE THE DIRECTIVE 

GENERATE DPB ON STACK, THEN 
EXECUTE DIRECTIVE 



1.7.7 



The ASTX$S Macro: Terminating AST Service 



The AST Service Exit macro is used to terminate execution 
service routine. All forms of the macro are provided. 
S-form is preferred because it requires less space and 
least as fast as the ASTX$ or ASTX$C form of the macro, 
issued in the following way: 

ASTX$S [err] 



of an AST 
However, the 
executes at 
The macro is 



err 

An optional argument which specifies the address of an error 
routine to which control branches if the directive is rejected. 

On completion of the operation specified in this macro call, if 
another AST is queued and asynchronous system traps have not been 
disabled, then the next AST is immediately entered. Otherwise, the 
task's state before the AST was entered is restored (it is the AST 
service routine's responsibility to save and restore the registers it 
uses) . 



1.7.8 The WTSE$ Macro: Waiting for an Event Flag 

The Wait For Single Event Flag macro instructs the system to suspend 
execution of the issuing task until the event flag specified in the 
macro call is set. This macro is extremely useful in synchronizing 
activity on completion of an I/O operation. All three forms of the 
macro call may be used. It is issued as follows: 

WTSE$ efn 
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efn 



The event flag number. 



WTSE$ causes the task to be blocked from execution until the specified 
event flag is set. Frequently, an efn parameter is also included in a 
QIO$ macro call, and the event flag is set on completion of the I/O 
operation specified in that call. The following example illustrates 
task blocking until the setting of the specified event flag occurs. 
This example also illustrates the use of the three forms of the macro 
call. 



DATA DEFINITIONS 



WAIT: 
lOSB: 



WTSE$ 5 
.BLKW 2 



GENERATE DPB 
I/O STATUS BLOCK 



EXECUTABLE SECTION 

ALUN$S #14.,#"MM ; ASSIGN LUN 14 TO MAGTAPE UNIT ZERO 

QIO$C 10. ATT, 14., 5 ; ATTACH DEVICE 

DIR$ #WAIT ; EXECUTE WAITFOR DIRECTIVE 



QIO$S #IO.RLB,#14.,#2,,#IOSB,,<#BUF,#80.> 

; READ RECORD, USE EFN2 



WTSE$S #2 



; WAIT FOR READ TO COMPLETE 



QIO$C 10 . WLB , 14 . , 3 , , lOSB , , <BUF , 80 . > 

; WRITE RECORD, USE EFN 3 



WTSE$C 3 



; WAIT FOR WRITE TO COMPLETE 



QIO$C I0.DET,14. ; DETACH DEVICE 



1.8 STANDARD I/O FUNCTIONS 



The number of input/output operations that can be specified by 
of the QIO directive is large. A particular operation 
requested by including the appropriate function code as the 
parameter of a QIO macro call. Certain functions are standard. 



means 

can be 

first 

These 
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functions are almost totally device independent and can thus be 
requested for nearly every device described in this manual. Others 
are device dependent and are specific to the operation of only one or 
two I/O devices. This section summarizes the function codes and 
characteristics of the following device- independent I/O operations: 

• Attach to an I/O device 

• Detach from an I/O device 

• Cancel I/O requests 

• Read a logical block 

• Read a virtual block 

• Write a logical block 

• Write a virtual block 

For certain physical device units discussed in this manual, a standard 
I/O function may be described as being a NOP. This means that no 
operation is performed as a result of specifying the function, and an 
I/O status code of IS.SUC is returned in the I/O status block 
specified in the QIO macro call. 

In the following descriptions and in formats shown in subsequent 
chapters, the five QIO directive parameters lun, efn, pri, isb, and 
ast are represented by the ellipsis (...) (see Section 1.5.1). 



1.8.1 10. ATT: Attaching to an I/O Device 

The function code 10. ATT is specified by a user task when that task 
requires exclusive use of an I/O device. This function code is 
included as the first parameter of a QIO macro call in the following 
way: 

QIO$C 10. ATT,... 

Successful completion of an 10. ATT request causes the specified 
physical device unit to be dedicated for exclusive use by the issuing 
task. This enables the task to process input or output in an unbroken 
stream and is especially useful on sequential, non-file-oriented 
devices such as terminals, card readers, and line printers. An 
attached physical device unit remains under control of the issuing 
task until it is explicitly detached by that task. To detach the 
device, the task can specify any LUN previously assigned to the 
attached device. 

While a physical device unit is attached, the I/O driver for that unit 
dequeues only I/O requests issued by the task that issued the attach. 
Thus, a request to attach a device unit already attached by another 
task will not be processed until the attachment is broken and no 
higher priority request exists for the unit. A LUN that is associated 
with an attached physical device unit may not be reassigned by means 
of an Assign LUN directive except when at least one LUN is still 
assigned to the attached device. 
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If the task that issued an attach function exits or is aborted before 
it issues a corresponding detach, the Executive automatically detaches 
the physical device unit. 



1.8.2 lO.DET: Detaching from an I/O Device 

The function code lO.DET is used to detach a physical device unit that 
has been previously attached by means of an 10. ATT request for 
exclusive use of the issuing task. This function code is included as 
the first parameter of a QIO macro call in the following way: 

QIO$C lO.DET,... 

The LUN specifications of both 10. ATT and lO.DET must be the same, as 
in the following example, which also illustrates the use of S- forms 

of several macro calls. 



.MCALL 
ALUN$S 



ALUN$S,QIO$S 
#14.,#"CR 



ASSOCIATE CARD READER WITH LUN 14 



QIO$S #10. ATT, #14. ; ATTACH CARD READER 



LOOP: QIO$S #I0.RLB,#14. ,.. . ; READ CARD 



QIO$S #I0.DET,#14. ; DETACH CARD READER 



1.8.3 lO.KIL: Canceling I/O Requests 

The function lO.KIL is issued by a task to cancel all of that 
I/O requests for a particular physical device unit. 



task ' s 



For I/O requests waiting for service — that is, in the I/O driver's 
queue — a status code of IE. ABO is returned in the I/O status block. 
An event flag is set, if specified. But any AST service routine that 
may have been specified is not initiated. 

For I/O requests being processed by an I/O driver — other than the 
disk or DECtape drivers — the IE. ABO status code is returned. Other 
status information (byte count, and so forth) is also returned in the 
I/O status block. An AST, if specified, is activated. 

For disk, DECtape, or DECtape II I/O requests being processed when an 
lO.KIL is issued, the lO.KIL acts as a NOP. The request is allowed to 
complete, except in the case in which a DECtape transfer is blocked by 
a select error. Because disk and DECtape operate quickly, lO.KIL 
simply causes the return of IS.SUC in the I/O status block. 

This function code is included as the first parameter of a QIO macro 
in the following way: 

QIO$C lO.KIL,... 

lO.KIL is useful in such special cases as canceling an I/O request on 
a physical device unit from which a response is overdue (for example, 
a read on a paper tape reader) . 
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1.8.4 lO.RLB: Reading a Logical Block 

The function code lO.RLB is specified by a task to read a block of 
data from the physical device unit specified in the macro call. This 
function code is included as the first parameter of a QIO macro in the 
following way: 

QIO$C lO.RLB, . . . ,<stadd,size,pn> 

stadd 

The starting address of the data buffer. 



size 

The data buffer size in bytes, 



pn 



One to four optional parameters, used to specify such additional 
information as block numbers for certain devices. 



1.8.5 lO.RVB: Reading a Virtual Block 

The function code lO.RVB is used to read a virtual block of data from 
the physical device unit specified in the macro call. A "virtual" 
block indicates a relative block position within a file and is 
identical to a "logical" block for such sequential, record-oriented 
devices as terminals and card readers. For these sequential, 
record-oriented devices, lO.RVB is converted to 10. RLE before being 
issued . 

NOTE 

Any subfunction bits specified in the 
lO.RVB request (see Sections 2.3.1 and 
3.3.1) are stripped off in this 
conversion. 

It is recommended that all tasks use virtual rather than logical 
reads. However, if a virtual read is issued for a file-structured 
device (disk, DECtape, or DECtape II), the user must ensure that a 
file is open on the specified physical device unit. This function 
code is included as the first parameter of a QIO macro call in the 
following way: 

QIO$C lO.RVB, ,<stadd,size,pn> 

stadd 

The starting address of the data buffer. 



size 

The data buffer size in bytes. 
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pn 

One to four optional parameters, used to specify such additional 
information as block numbers for certain devices. 



1.8.6 lO.WLB: Writing a Logical Block 

The function code lO.WLB is specified by a task to write a block of 
data to the physical device unit specified in the macro call. This 
function code is included as the first parameter of a QIO macro call 
in the following way: 

QIO$C lO.WLB,. . .,<stadd,size,pn> 

stadd 

The starting address of the data buffer. 



size 



pn 



The data buffer in bytes. 



One to four optional parameters, used to specify such additional 
information as block numbers or format control characters for 
certain devices. 



1.8.7 lO.WVB: Writing a Virtual Block 

The function code lO.WVB is used to write a virtual block of data to a 
physical device unit. A "virtual" block indicates a block position 
relative to the start of a file. For sequential, record-oriented 
devices such as terminals and line printers, the function lO.WVB is 
converted to lO.WLB. 



NOTE 

Any subfunction bits specified in the 
lO.WVB request (see Sections 2.3.1 and 
3.3.1) are stripped off in this 
conversion. 



It is recommended that all tasks use virtual rather than logical 
writes. However, if a virtual write is issued for a file-structured 
device (disk, DECtape, or DECtape II), the user must ensure that a 
file is open on the specified physical device unit. This function 
code is included as the first parameter of a QIO macro call in the 
following way: 

VxU^v^ xo. ini vo , . • . , vS L.auu , £3 X it: , pny' 

stadd 

The starting address of the data buffer. 
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Size 



pn 



The data buffer size in bytes. 



One to four optional parameters, used to specify such additional 
information as block numbers or format control characters for 
certain devices. 



1.8.8 User-Mode Diagnostic Functions 

The I/O function code subfunction bit, IQ.UMD, provides support for 
user-mode diagnostics. To perform a diagnostic function, you must 
specify in the QIO directive parameter block the logical OR of IQ.UMD 
and the function you want to perform. For example, to perform a 
diagnostic Read Logical Block operation, specify 10. RLB! IQ.UMD as the 
I/O function code parameter to the QIO directive. You can perform 
standard I/O functions such as Read Logical Block, Write Logical 
Block, Attach to Device, and Detach from Device in diagnostic mode. 

Support for user-mode diagnostics is always present for RSX-llM-PLUS, 
but not all drivers support user-mode diagnostic functions. 
Unpredictable device and driver behavior results when you set the 
IQ.UMD subfunction bit in QIOs that are directed to the device if it 
does not support user-mode diagnostics. Problems can be avoided if 
you do a Get LUN directive and check the user-mode diagnostics bit 
before emitting the user-mode diagnostic QIO. 

To support user-mode diagnostics, the DV.UMD bit in the UCB must be 
set. DV.UMD is at offset U.CWl in the UCB. 

In addition to standard I/O functions, RSX-llM-PLUS provides the 
following device-dependent, user-mode diagnostic functions: 

1. Disk diagnostic functions 

lO.HMS Home seek or recalibrate 

lO.BLS Block seek (explicit seek) 

10. OFF Offset position 

lO.RDH Read disk header 

lO.WDH Write disk header 

lO.WCK Writecheck 
DECtape diagnostic functions 

lO.RNF Read block number forward 

lO.RNR Read block number reverse 
3. Magtape diagnostic functions 

lO.LPC Read longitudinal parity character 

lO.ERS Erase tape 
UMDIO$ is the macro that defines these functions. 
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To execute a user-mode diagnostic function, you must first attach for 
diagnostics using I/O function code 10. ATT! IQ.UMD- Execute the 
diagnostic functions and then detach. 

The parameter list in words 1 through 6 of the DPB should contain the 
following information: 

• I/O buffer address 

• I/O buffer size 

• Offset factor for disks with offset recovery (to determine the 
offset factor, refer to the offset register in the hardware 
reference manual) ; this parameter is not used if the device 
does not have offset recovery. 

• Double-precision logical block number 

• User's register buffer address (the I/O driver copies its 
hardware registers to this buffer in the user's program); see 
a hardware reference manual for the length of the address 



A typical DPB for a diagnostic function might look like the followi 



ng : 



$DSKPB: 





.BYTE 


3,12. 




• WORD 


lO.WDHUO.UMD 




.WORD 


THELUN 




.BYTE 


THEEFN,0 




.WORD 


SIOSTS 




.WORD 





SIOBUF: 


.WORD 







.WORD 







.WORD 





SLBH:: 


.WORD 





$LBL: : 


• WORD 







.WORD 


$RGBUF 



Size of the DPB, QIOWAIT directive code 

I/O function code 

Logical Unit Number 

Event flag number 

I/O status block address 

AST address 

Buffer address 

Transfer size in bytes 

Device dependent 

High-order logical block number 

Low-order logical block number 

Register buffer address 

The user-mode diagnostic functions return either Success (IS.SUC) or 
Device Not Ready (lE.DNR). No other error codes are returned. All 
error recovery is completely up to the user. Any errors that occur 
will not be logged in the error log. 

A typical program fragment, using the user-mode diagnostic functions, 
might look like the following: 

.MCALL UMDIO$,ALUN$S,QIO$S 
UMDIO$ ; Define diagnostic functions 

ALUN$S #14.,#"DM,#0 ; Associate DM0 with lun 14 

QIO$S #14.,#"DM,#0 ; Associate DM0 with lun 14 



QIOSS #I0.ATT!IQ.UMD,#14. 



Attach DM for diagnostic I/O 



OIOSS #IO.RDH!I0.UMD,#14.,,,,,<#$IOBUF,#512.,,#LBH,#LBL,#$RGBUF> ; Read disk header 
QIOSS #I0.RLB!IQ.UMD,#14.,,,,,<#SI0BUF,#512.,,#LBH,#LBL,#$RGBUF> ; Read logical block 



QIO$S #I0.DET!IQ.UMD,#14. 



Detach DM 
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1.9 I/O COMPLETION 



When an I/O request has been completed, either successfully or 
unsuccessfully, one or more actions may be taken by the Executive. 
Selection of return conditions depends on the parameters included in 
the QIO macro call. There are three major returns: 

1. A significant event is declared on completion of an I/O 
operation. If an efn parameter was included in the I/O 
request, the corresponding event flag is set. 

2. If an isb parameter was specified in the QIO macro call, a 
code identifying the type of success or failure is returned 
in the low-order byte of the first word of the I/O status 
block at the location represented by isb. 

This status return code is of the form IS.xxx (success) or 
IE. XXX (error). For example, if the device accessed by the 
I/O request is not ready, a status code of lE.DNR is returned 
in isb. The section below (Return Codes) summarizes general 
codes returned by most of the drivers described in this 
manual . 

If the isb parameter was omitted, the requesting task cannot 
determine whether the I/O request was successfully completed. 
A carry clear return from the directive itself simply means 
that the directive was accepted and the I/O request was 
queued, not that the actual input/output operation was 
successfully performed. 

3. If an ast parameter was specified in the QIO macro call, a 
branch to the AST service routine that begins at the location 
identified by ast occurs on completion of the I/O operation. 
See Section 1.5.3 for a detailed description of AST service 
routines. 



1.10 RETURN CODES 

There are two kinds of status conditions recognized and handled by 
RSX-llM/M-PLUS when they occur in I/O requests: 

Directive conditions, which indicate the acceptance or 
rejection of the QIO directive itself 

I/O status conditions, which indicate the success or failure 
of the I/O operation 



Direc 
the f 



ive conditions relevant to I/O operations may indicate any of 
llowing : 

Directive acceptance 

Invalid buffer specification 

Invalid efn parameter 

Invalid lun parameter 

Invalid DIG number or DPB size 

Unassigned LUN 

Insufficient memory 
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A code indicating the acceptance or rejection of a directive is 
returned to the Directive Status Word at symbolic location $DSW. This 
location can be tested to determine the type of directive condition. 



I/O conditions ind 
specified in the 
conditions as devi 
open, or write-lo 
QIO directive, ide 
an I/O status code 
of this block on c 
binary value cor 
IE. XXX. The low-o 
name, to determi 
between global sym 
codes is defined 
definitions may al 
which reside in 
Appendix B. 



icate the success or failure of the I/O operation 
QIO directive. I/O driver errors include such 
ce not ready, privilege violation, file already 
eked device. If an isb parameter is included in the 
ntifying the address of a 2-word I/O status block, 

is returned in the low-order byte of the first word 
ompletion of the I/O operation. This code is a 
responding to a symbolic name of the form IS.xxx or 
rder byte of the word can be tested symbolically, by 
ne the type of status return. The correspondence 
bolic names and directive and I/O completion status 
in the system object module library. Local symbolic 
so be obtained by the DRERR$ and IOERR$ macros, 

the System Macro Library and are summarized in 



Binary values of status codes always have the following meanings; 

Code Meaning 



Positive (greater than 0) 



Negative 



Successful completion 
Operation still pending 
Unsuccessful completion 



A pending operation means that the I/O request is still in the queue 
of requests for the respective driver, or the driver has not yet 
completely serviced the request. 



1.10.1 Directive Conditions 

Table 1-2 summarizes the directive conditions that may be encountered 
in QIO directives. The acceptance condition is first, followed by 
error codes indicating various reasons for rejection, in alphabetical 
order. 



Table 1-2 
Directive Conditions 



Code 



IS. sue 



Reason 



Directive accepted 

The first six parameters of the QIO directive were 
valid, and sufficient dynamic memory was available 
to allocate an I/O packet. The directive is 
accepted. 

Invalid address 

The I/O status block or the QIO DPS was outside of 
the issuing task's address space or was not aligned 
on a word boundary. 



(continued on next page) 
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Table 1-2 (Cont.) 
Directive Conditions 



Code 



lE.IEF 



lE.ILU 



lE.SDP 



Reason 



lE.ULN 



lE.UPN 



Invalid event flag number 

The efn specification in a QIO directive was less 
than or greater than 96. 

Invalid logical unit number 

The lun specification in a QIO directive was 
invalid for the issuing task. For example, there 
were only 5 logical unit numbers associated with 
the task, and the value specified for lun was 
greater than 5. 

Invalid DIG number or DPB size 

The directive identification code (DIC) or the size 
of the Directive Parameter Block (DPB) was 
incorrect; the legal range for a DIC is from 1 
through 127, and all DIC values must be odd. Each 
individual directive requires a DPB of a certain 
size. If the size is not correct for the 
particular directive, this code is returned. The 
size of the QIO DPB is always 12 words. 

Unassigned LUN 

The logical unit number in the QIO directive was 
not associated with a physical device unit. The 
user may recover from this error by issuing a valid 
Assign LUN directive and then reissuing the 
rejected directive. 

Insufficient dynamic memory 

There was not enough dynamic memory to allocate an 
I/O packet for the I/O request. The user can try 
again later by blocking the task with a Waitfor 
Significant Event directive. Note that Waitfor 
Significant Event is the only effective way for the 
issuing task to block its execution, since other 
directives that could be used for this purpose 
themselves require dynamic memory for their 
execution (for example, Mark Time). 



1.10.2 I/O Status Conditions 

The following list summarizes status codes that may be returned in the 

I/O status block specified in the QIO directive on completion of the 

I/O request. The I/O status block is a 2-word block with the 
following format: 

• The low-order byte of the first word receives a status code of 
the form IS.xxx or lE.xxx on completion of the I/O operation. 

• The high-order byte of the first word is usually device 
dependent; in cases where the user might find information in 
this byte helpful, this manual identifies that information. 
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• The second word contains the number of bytes transferred or 
processed if the operation Is successful and involves reading 
or writing. 

If the isb parameter of the QIO directive is omitted, this information 
is not returned. 



The following illustrates a sample 2-word 
completion of a terminal read operation: 



I/O status block on 



Byte 






-10 


Numbe r 


of bytes read 



Word 



where -10 is the status code for IE. EOF (end of file). If this code 
is_ returned, it indicates that input was terminated by typing CTRL/Z, 
which is the end-of-file termination sequence on a terminal. 

To test for a particular error condition, the user generally compares 
the low-order byte of the first word of the I/O status block with a 
symbolic value, as in the following: 



CMPB 



#IE.DNR,IOSB 



However, to test for 
operation, the entir 
carriage return termi 
successful completio 
block. If an Escape 
of IS. ESC is retur 
first test the low-or 
IS. sue and then te 
IS. ESQ. (Other succe 
listed in Appendix B, 



certain types of successfu 
e word value must be compa 
nated a line of input 
n code of IS.CR is ret 
(or Altmode) character was 
ned . To check for these 
der byte of the first wo 
St the full word for I 
ss codes that must be read 
Section B.1.2.) 



1 completion of the I/O 

red. For example, if a 

from the terminal, a 

urned in the I/O status 

the terminator, a code 

codes, the user should 

rd of the block for 

S.CC, IS.CR, IS. ESC, or 

in this manner are 



Note that both of the following comparisons will test as equal 
the low-order byte in both cases is +1. 



since 



CMP #IS.CR,IOSB 
CMPB #IS.SUC,IOSB 

In the case of a successful completion where the carriage return is 
the terminal indicator (IS.CR), the following illustrates the status 
block: 



Byte 



Word 



15 



+1 



Number of bytes read 
(excluding the CR) 



where 15 is the octal code for carriage return and +1 
code for successful completion. 



is the status 



The codes described in Table 1-3 are general status codes that apply 
to the majority of devices presented in subsequent chapters. Error 
codesspecific to only one or two drivers are described only in 
relation to the devices for which they are returned. The list below 
describes successful and pending codes first ther 
alphabetical order. 



■ i. i. KJ L 



^ KJKA CO 
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IS. sue 



IS.PND 



IE. ABO 



lE.ALN 



IE. BAD 



IE. BEE 



lE.BLK 



IE. BYT 
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Table 1-3 
I/O Status Conditions 



Reason 



Successful completion 

The I/O operation specified in the QIO directive 
was completed successfully. The second word of the 
I/O status block can be examined to determine the 
number of bytes processed, if the operation 
involved reading or writing. 

I/O request pending 

The I/O operation specified in the QIO directive 
has not yet been executed. The I/O status block is 
filled with Os. 

Operation aborted 

The specified I/O operation was cancelled with 
lO.KIL while in progress or while still in the I/O 
queue. 

File already open 

The task attempted to open a file on the physical 
device unit associated with the specified LUN, but 
a file has already been opened by the issuing task 
on that LUN. 

Bad parameter 

An illegal specification was supplied for one or 
more of the device-dependent QIO parameters (words 
6-11). For example, a bad channel number or gain 
code was specified in an analog-to-digital 
converter I/O operation. 

Bad block on device 

One or more bad blocks were found by executing the 
BAD utility. Data cannot be written on bad blocks. 

Illegal block number 

An illegal block number was specified for a 
file-structured physical device unit. This code is 
returned, for example, if block 4800 is specified 
for an RK05 disk, on which legal block numbers 
extend from through 4799. 

Byte-aligned buffer specified. 

Byte alignment was specified for a buffer, but only 
word (or double-word) alignment is legal for the 
physical device unit. For example, a disk function 
requiring word alignment was requested, but the 
buffer was aligned on a byte boundary. 
Alternately, the length of a buffer was not an 
appropriate multiple of bytes. For example, all 
RP03 disk transfers must be an even multiple of 
four bvtes. 



(continued on next page) 
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Code 



lE.DAA 



Table 1-3 (Cont.) 
I/O Status Conditions 



Reason 



Device already attached 



lE.DNA 



lE.DNR 



IE. EOF 



lE.FHE 



IE. IPC 



lE.NLN 



IE. NOD 



The physical device unit specified in an 10. ATT 
function was already attached to the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. 

Device not attached 

The physical device unit specified in an lO.DET 
function was not attached to the issuing task. 
This code has no bearing on the attachment status 
with respect to other tasks. 

Device not ready 

The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. This code is often returned as the 
result of an interrupt time-out; that is, a 
"reasonable" amount of time has passed, and the 
physical device unit has not responded. 

End-of-file encountered 

An end-of-file mark, record, or control character 
was recognized on the input device. 

Fatal hardware error 



Controller is physically unable to reach the 
location where input/output is to be performed on 
The operation cannot be completed. 



the device. 



Illegal function 

A function code was specified in an I/O request 
that was illegal for the specified physical device 
unit. This code is returned if the task attempts 
to execute an illegal function or if, for example, 
a read function is requested on an output-only 
device, such as the line printer. 

File not open 

The task attempted to close a file on the physical 
device unit associated with the specified LUN, but 
no file was currently open on that LUN. 

Insufficient buffer space 

Dynamic storage space has been depleted, and there 
was insufficient buffer space available to allocate 
a secondary control block. For example, if a task 
attempts to open a file, buffer space for the 
window and file control block must be supplied by 
the Executive. This code is returned when there is 
not enough space for such an operation. 



(continued on next page) 
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lE.OFL 



lE.OVR 



lE.PRI 



lE.SPC 



lE.VER 



lE.WCK 



lE.WLK 
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Table 1-3 (Cont.) 
I/O Status Conditions 



Reason 



Device off line 



The physical device unit associated with the _ LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 

Illegal read overlay request 

A read overlay was requested and the physical 
device unit specified in the QIO directive was not 
the physical device unit from which the task was 
installed. The read overlay function can only be 
executed on the physical device unit from which the 
task image containing the overlays was installed. 

Privilege violation 

The task that issued a request was not privileged 
to execute that request. For example, for the 
UDCll and LPSll, a checkpointable task attempted to 
connect to interrupts or to execute a synchronous 
sampling function. 

Illegal address space 

The buffer requested for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternately, a byte count of 
was specified. 

Unrecoverable error 

After the system's standard number of retries have 
been attempted upon encountering an error, the 
operation still could not be completed. This code 
is returned in the case of parity, CRC, or similar 
errors. 

Write check error 

An error was detected during the check (read) 
following a write operation. 

Write-locked device 

The task attempted to write on a write-locked 
physical device unit. 
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1.11 POWER-FAIL RECOVERY PROCEDURES FOR DISKS AND DECTAPE 

Power-fail recovery recommendations for various devices are included 
in the following chapters, as appropriate, to assist the user in 
restoring device operation after a power failure. For disks and 
DECtape, it is recommended that power recovery ASTs be used. The AST 
service routine should provide a sufficient time delay, prior to 
returning for normal I/O operations, that will allow the disk to 
attain normal operating speed before actually attempting read and 
write operations. 

If QIOs are being used for disk or DECtape I/O operations during 
power-fail recovery, an lE.DNR error status may be returned if the 
device is not up to operating speed when the request is issued. When 
this error is returned, it is recommended that the user task wait a 
sufficient time for the device to attain operating speed, and attempt 
the I/O operation again prior to reporting an error. For example, an 
RK05 disk may require approximately 1 minute to attain operating speed 
after a power failure. 
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CHAPTER 2 
FDLL-DDPLEX TERMINAL DRIVER 



2.1 INTRODUCTION 

Two terminal drivers are available as SYSGEN options for use in 
RSX-llM systems: 

1. A compact, half-duplex terminal driver for use with a wide 
variety of terminals, containing all basic features required 
for RSX-llM terminal support. (This terminal driver is not 
available on RSX-llM-PLUS systems.) This terminal driver is 
described in Chapter 3. 

2. A full-duplex terminal driver, as described in this chapter, 
containing all features of the half-duplex terminal driver, 
plus the following: 



• 



Full-duplex operation 



• Type-ahead buffering 



• 



Eight-bit characters 



• Detection of hard receive errors 



• 



Increased byte transfer length (8128 bytes) 



• Additional terminal characteristics 



Additional terminal types 

Optional time-out on solicited and/or unsolicited input 

Device-independent cursor control 

Redisplay of prompt buffer upon CTRL/R or CTRL/U 

Automatic XOFF character generation upon completion of a 
read (except when in the full-duplex mode) , if requested 

Autobaud speed detection 

Added hardware support 

Note that either terminal driver can be selected during RSX-llM 
SYSGEN. RSX-llM-PLUS systems use the full-duplex terminal driver 
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Throughout the remainder of this chapter, references made to MCR can 
generally be applied to other command line interpreters (for example, 
DCL) . In addition, the prompt displayed on a terminal in response to 
invoking a command line interpreter will be appropriate for the 
specific command line interpreter in use. For example, when MCR is 
invoked, the MCR prompt is displayed as follows: 

MCR> 

Terminal driver support is provided for a variety of terminal devices, 
as listed in Table 2-1. Subsequent sections describe each device in 
greater detail. 



Table 2-1 
Supported Terminal Devices 



Model 


Columns 


Lines/, 
Screen 


Character 
Set 


Baud 
Range 


Upper- & Lowercase? 


Send 


Receive 


ASR-33/35 


72 




64 


110 






KSR-33/35 


72 




64 


110 






LA12 


132 




96 


50-9600 


yes 


yes 


LAIOO 


132 




96 


110-9600 


yes 


yes 


LA30-P 


80 




64 


300 






LA30-S 


80 




64 


110-300 






LA34 


132 




96 


110-300 


yes 


yes 
yes^ 


LA36 


132 




64-96 


110-300 


yes 


LA38 


132 




96 


110-300 


yes 


yes 


LA120 


132 




96 


50-9600 


yes 


yes 


LA180S 


132 




96 


300-9600 




yes 


LQP02 


132/158 






110-9600 






LA50 


80/96/132 






110-4800 






RT02 


64 


1 


64 


110-1200 






RT02-C 


64 


1 


64 


110-1200 






VT0 5B 


72 


20 


64 


110-2400 


yes 




VT50 


80 


12 


64 


110-9600 






VT50H 


80 


12 


64 


110-9600 






VT52 


80 


24 


96 


110-9600 


yes 


yes 


VT55 


80 


24 


96 


110-9600 


yes 


yes 


VT61 


80 


24 


96 


110-9600 


yes 


yes 


VTIOO 


80-132 


24 


96 


50-9600 


yes 


yes 


VTlOl 


80-132 


24 


96 


50-19200 


yes 


yes 


VT102 


80-132 


24 


96 


50-9600 


yes 


yes 


VT105 


80-132 


24 


96 


50-19200 


yes 


yes 


VT125 


80-132 


24 


96 


50-9600 


yes 


yes 


VT131 


80-132 


24 


96 


50-19200 


yes 


yes 


VT132 


80-132 


24 


96 


50-19200 


yes 


yes 



1. Applies only to video terminals. 

2. Only for 96-character terminal. The terminal driver supports the 
terminal interfaces summarized in Table 2-2. These interfaces are 
described in greater detail in Section 2.9. Programming is identical 
for all interfaces. 
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Table 2-2 
Standard Terminal Interfaces 



Model 



DHll 

DHVll 

DHll-DMll-BB 

DJll 

DLll-A/B/C/D/E/W 

DLVll-E/F 

DZll 



Type 



16-line multiplexer-*- 

8-line multiplexer^ 

16-line multiplexer with modem control2 

16-line multiplexer 

Single-line interfaces 

Single-line interfaces3 

8-line multiplexer with modem control-^ 



1. Direct memory access (DMA) is 
full-duplex terminal driver only. 



supported in the 



2. Full-duplex control only. For example, in the USA, a 
Bell 103A-type modem. 

3. DLVll and DHVll support with modem control is provided 
in the full-duplex terminal driver only. 

Terminal input lines can have a maximum length of 8128 (8K minus 64) 
bytes. Extra characters of an input line that exceed the maximum line 
length generally become an unsolicited input line if the terminal is 
not attached with typeahead enabled. 



2,1.1 ASR-33/35 Teletypes* 

The ASR-33 and ASR-35 Teletypes are asynchronous, hard-copy terminals. 
No paper-tape reader or punch capability is supported. 



2.1.2 KSR-33/35 Teletypes* 

The KSR-33 and KSR-35 Teletypes are asynchronous, hard-copy terminals, 

2.1.3 LA12 Portable Terminal 

The LA12 is a personal, portable, hard-copy terminal. 

2.1.4 LAIOO DECpr inter 

The LAIOO is a desk-top, matrix, hard-copy terminal. 



1. Teletype is a registered trademark of the Teletype Corporation. 
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2.1.5 LA30 DECwr iters 

The LA30 DECwr iter is an asynchronous, hard-copy terminal that is 
capable of producing an original and one copy. The LA30-P is a 
parallel model and the LA30-S is a serial model. 



2.1.6 LA36 DECwriter 

The LA36 DECwriter is an asynchronous terminal that produces hard copy 
and operates in serial mode. It has an impact printer capable of 
generating multipart and special preprinted forms. The LA36 can 
receive and transmit both uppercase and lowercase characters. 



2.1.7 LA34/38 DECwriters 

The LA34 DECwriter is an asynchronous terminal that produces hard copy 
and uses a platen paper feed mechanism. 

The LA38 DECwriter includes a detachable tractor feed mechanism for 
use with continuous forms. 



2.1.8 LA120 DECwriter 

The LA120 DECwriter is a hard-copy, upper- and lowercase terminal, 
capable of printing multipart forms at speeds up to 180 
characters-per-second. Serial communications speed is selected from 
14 baud rates ranging from 50 to 9600 bps; split transmit and receive 
baud rates are supported by the terminal driver. Hardware features 
allow bidirectional printing for maximum printing speed, and also 
allow user-selected features, including font size, line spacing, tabs, 
margins, and forms control. These functions can also be set up by the 
system by issuing appropriate ANSI-standard escape sequences. 



2.1.9 LA180S DECprinter 

The LA180S DECprinter is a serial version of the LA180. It is a 
print-only device (it has no keyboard) that can generate multipart 
forms. The LA180S can print uppercase and lowercase letters. 



2.1. 9A LQP02 Letter-Quality Printer 

The LQP02 Letter-Quality Printer is a formed character, desktop 
printer incorporating daisywheel technology. This letter-quality 
printer offers over 100 character sets and handles regular office 
stationery up to a maximum of 15 inches, but the print capacity is 
13.5 inches. The lines per inch and characters per inch are software 
selectable; characters at 10 and 12 and lines at 2, 3, 4, 6, and 8. 
At 10 characters per inch you get 132 columns and at 12 characters you 
get 158 columns. The buffer capacity is 256 characters. 
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2.1. 9B LA50 Personal Printer 



The LA50 Personal Printer is a desktop dot-matrix impact printer. it 
ha^ two print modes; text mode and enhanced print mode. In text 
mode It prints at 100 characters per second. ?he enhanced prtnt 
quality mode prints at 50 characters per second and creates a crilper, 
ohnL^"'K°''"' character than an ordinary dot-matrix printer. You ca.^ 
choose characters per inch at 10, 12, or 16 which gives columns at 80? 

s'255 characters"" ^"" "'' '"" '" '' '' ""^ '^ ' '^"^ ^^"^^ ^P^^^^ 



2.1.10 RT02 Alphanumeric Display Terminal and RT02-C Badqe 
Reader/Alphanumeric Display Terminal 

aSolfc^Mnn/ ?r^^^^'v, alphanumeric display terminal designed for 
n£^ii^! iS i "^'''' ^°"''''^ ^^^^ ^^ primarily numeric. A shift key 
permits the entry of 30 discrete characters, including uppercase 

character s.^^'""'^"'- ^""^ ^^'' ^^"' however, deceive and^display 64 

r^TJh?^"^ ?K^!^ t^^°. contains a badge reader. This option provides a 
reliable method of identifying and controlling access to the PDP-11 or 
tSa? oTTLt'l ^0^- /"^thermore, data in a format corresponding to 
that of a badge (22-column fixed data) can be entered quickly. 
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2.1,11 VT05B Alphanumeric Display Terminal 

The VT05B is an alphanumeric display terminal that consists of a CRT 
display and a self-contained keyboard- From a programming point of 
view, it is equivalent to other terminals, except that the VT05B 
offers direct cursor addressing. 



2.1.12 VT50 Alphanumeric Display Terminal 

The VT50 is an alphanumeric display terminal that consists of a CRT 
display and a keyboard. It is similar to the VT05B in operation, but 
does not offer direct cursor addressing. 



2.1.13 VT50H Alphanumeric Display Terminal 

The VT50H is an alphanumeric display terminal with CRT display, 
keyboard, and numeric pad. It offers direct cursor addressing. (The 
VTSOH's direct cursor addressing is not compatible with that of the 
VT05B.) 



2.1.14 VT52 Alphanumeric Display Terminal 

The VT52 is an upper- and lowercase alphanumeric terminal with numeric 
pad and direct cursor addressing. (The VT52's direct cursor 
addressing is compatible with that of the VT50H, not with that of the 
VT05B.) The VT52 can be configured with a built-in thermal printer. 



2.1.15 VT55 Graphics Display Terminal 

The VT55 is similar to the VT52 in its operation as an alphanumeric 
terminal. The VT55 offers graphics display features that are not 
supported by RSX-llM, although the system allows a knowledgeable task 
to access the explicitly special features of the VT55. 



2.1.16 VT61 Alphanumeric Display Terminal 

The VT61 is an "intelligent" upper- and lowercase alphanumeric 
terminal with an integral microprocessor. It offers two 128-member 
character sets and numerous built-in functions for editing and forms 
preparation as well as a block-transfer mode. (None of these special 
features is supported by RSX-llM.) 



2.1.17 VTIOO DECscope 

The VTIOO DECscope is" an upper- and lowercase alphanumeric 
keyboard/video display terminal. It is capable of displaying 24 lines 
of 80 to 132 characters (each line) . Serial communications speed is 
selected from baud rates ranging from. 50 to 9600 bps. Hardware 
features allow user selection of display characteristics and functions 
including smooth scroll, reverse video, and so forth. These functions 
can also be set up by the system by issuing appropriate ANSI-standard 
escape sequences. 
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2.1.18 VTlOl DECscope 

The VTlOl DECscope is functionally identical to the VTIOO. However, 
it does not support the advanced video features. 



2.1.19 VT102 DECscope 

The VT102 DECscope is functionally identical to the VTIOO. However, 
it does not have any expansion capability and does not support the 
advanced video features. It has enhanced modem control and it 
includes a port for a printer. 



2.1.20 VT105 DECscope 

The VT105 DECscope is a video terminal. It has both alphanumeric and 
graphic display. The VT105 can display two graphs, two shaded graphs, 
or two strip charts. These graphs may have alphanumeric labels. 



2.1.21 VT131 DECscope 

The VT131 is the same as the VT102 with the addition of built-in 
editing features. 



2.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for terminals. A setting of 1 indicates that the 
described characteristic is true for terminals. 

Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 



Bit 


Setting 





1 


1 


1 


2 


1 


3 





4 





5 





6 





7 





8 





9 
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Meaning 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications 
channel 

Device mountable as a FILES-11 volume 

Device mountable 

Words 3 and 4 of the buffer are undefined. Word 5 indicates the 
default buffer size (the width of the terminal carriage or display 
screen) . 



Bit 


Setting 


10 





11 





12 





13 





14 





15 






2.3 QIO MACRO 

Table 2-3 lists the standard and device-specific functions of the QIO 
macro that are valid for terminals. Some device-specific functions 
are options that may be selected during SYSGEN. 

Two device-specific functions, SF.SMC and SF.GMC, have nonstandard 
function names. These names are retained for compatibility with 
RSX-llD. 



Table 2-3 
Standard and Device-Specific QIO Functions for Terminals 



Format 


Function 


STANDARD FUNCTIONS: 

QIO$C 10. ATT,... 

QIO$C lO.DET,... 

QIOSC lO.KIL,... 

QIO$C lO.RLB, . . . ,<stadd,size [ ,tmo] > 

QIO$C lO.RVB, . . . ,<stadd,size[,tmo] > 

QIO$C lO.WLB,. .. ,<stadd,size,vfc> 

QIOSC lO.WVB, . . . ,<stadd,size,vfc> 


Attach device. 

Detach device. 

Cancel I/O requests. 

READ logical block 
(read typed input into 
buffer) . 

READ virtual block 
(read typed input into 
buffer) . 

WRITE logical block 
(print buffer 
contents) . 

WRITE virtual block 
(print buffer 
contents) . 
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Table 2-3 (Cont.) 
Standard and Device-Specific QIO Functions for Terminals 



Format 


Function 


DEVICE-SPECIFIC FUNCTIONS: 




QIO$C lO.ATA, . .. ,<ast, 

[paraineter2] [,ast2]>l 


ATTACH device, specify 
unsolicited-input- 
character AST. 


QIO$C 10. ceo, . . . ,<stadd,size,vfc> 


CANCEL CTRL/O (if in 
effect) , then write 
logical block. 


QIO$C SF.GMC,. .. ,<stadd,size>l 


GET multiple 
characteristics. 


QIO$C lO.GTS, . . . ,<stadd,size>l 


GET terminal support. 


QIO$C lO.HNG,.., 


HANGUP remote line. 


QIO$C lO.RAL, , . . ,<stadd,size[,tmo] > 


READ logical block, 
pass all bits. 


QIOSC lO.RNE, . . . ,<stadd ,size[,tmo] > 


READ logical block, do 
not echo. 


QIOSC lO.RPR, . .. ,<stadd,size, 

[tmo] ,pradd,prsize,vfc>l 


READ logical block 
after prompt. 


QIO$C lO.RST, . . . ,<stadd,size[,tmo] > 


READ logical block 
ended by special 
terminators. 


QIOSC lO.RTT,. . . ,<stadd,size, 
[tmo] ,table> 


READ logical block 
ended by specified 
special terminator. 


QIO$C SF.SMC, . , .,<stadd,size>l 


SET multiple 
characteristics. 


QIO$C lO.WAL, . . . ,<stadd,size,vfc> 


WRITE logical block, 
pass all bits. 


QIO$C lO.WBT,. ..,<stadd,size,vfc>l 


WRITE logical block, 
break through any I/O 
conditions at 
terminal . 



ast 



The entry point for an unsolicited- input-character AST. 



parameter 2 



A number that can be used to identify this terminal as the input 
source upon entry to an unsolicited character AST routine. 



1. SYSGEN options in RSX-llM. 
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ast2 

The entry point for an unsolicited CTRL/C AST. 

pradd 

The starting address of the byte buffer where the prompt is 
stored. 



prsize 



The size of the pradd prompt buffer in bytes. The specified size 
must be greater than and less than or equal to 8128. The 
buffer must be within the task's address space. 



size 



The size of the stadd data buffer in bytes. The specified size 
must be greater than and less than or equal to 8128. The 
buffer must be within the task's address space. For SF.GMC, 
10. GTS, and SF.SMC functions, size must be an even value. 

stadd 

The starting address of the data buffer. The address must be 
word aligned for SF.GMC, 10. GTS, and SF.SMC; otherwise, stadd 
may be on a byte boundary. 

table 

The address of the 16-word special terminator table. 



tino 



vfc 



An optional time-out count in 10-second intervals for the 
full-duplex terminal driver. If is specified, no time-out can 
occur. Time-out is the maximum time allowed between two input 
characters before the read is aborted. The maximum timeout value 
is 255. 



A character for vertical format control from Table 2-11 (see 
Section 2.7) . 



2.3.1 Subf unction Bits 

Most device-specified functions supported by terminal drivers 
described in this section are selected using "subf unction bits." One 
or more functions can be selected by ORing their relative bits in a 
QIO function. Table 2-4 contains a listing of QIO functions and 
relative subf unction bits that can be issued. 
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Each subfunction bit and subfunction selected when it is included in a 
QIO function is listed as follows: 

Symbolic 

Name Subfunction 

TF.AST Unsolicited-input-character AST 

TF.BIN Binary prompt 

TF.CCO Cancel CTRL/0 

TF.ESQ Recognize escape sequences 

TF.NOT Unsolicited input AST notification; unsolicited 

characters are stored in the type-ahead buffer 

until they are read by the task 
TF.RAL Read all bits 

TF.RCU Restore cursor position 

TF.RNE Read with no echo 

TF.RST Read with special terminators 

TF.TMO Read with time-out 

TF.WAL Write all bits 

TF.WBT Break-through write 

TF.XCC CTRL/C starts a command line interpreter command 

line (Command line characters are not sent to 

the task.) 
TF.XOF Send XOFF 

Table 2-4 lists subfunction bits that can be ORed with QIO functions. 
Additional details for using subfunction bits are included in Section 
2.3.2. 

If a task invokes a subfunction bit that is not supported on the 
system, the subfunction bit is ignored, but the QIO request is not 
rejected. For example, if break-through write (TF.WBT) is not 
selected, an lO.WBT or lO.WLBiTF.WBT function is interpreted as an 
lO.WLB function. 

The following example is a QIO request using more than one subfunction 
bit: a nonechoed (TF.RNE) read, terminated by a special terminator 
character (TF.RST) and preceded by a prompt. 

QIO$C I O. RPR ITF.RNEl TF.RST, . . . ,<stadd ,si ze , ,pradd ,prsize ,vf c> 



2.3.2 Device-Specific QIO Functions 

Some device-specific functions described in this section are SYSGEN 
options. All except SF.GMC, 10. RPR, SF.SMC, lO.RTT, and 10. GTS can be 
issued by ORing a particular subfunction bit with another QIO 
function. These subfunction bits are specified in the following 
descriptions; subfunction bits are described in general in Section 
2.3.1. 

In addition to the device-specific QIO functions, this section also 
describes the use of subfunction bits TF.ESQ, TF.BIN, and TF.XOF. 
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Table 2-4 
Subfunction Bits - Summary 



I 













Allowed Subfunction 


Bits 














Equivalent 
Subf unctions 






















Function 


TF.AST 


TF.BIN 


TF.CCO 


TF.ESQ 


TF.NOT 


TF.RAL 


TF.RCU 


TF.RNE 


TF.RST 


TF.TMO 


TF.WAL 


TF.WBT 


TF.XCC 


TF.XOF 


STANDARD FUNCTIONS 


X 






X 






















10. ATT 




rO.DET 
































lO.KIL 
































lO.RLB 














1 




X 


1 


X 








X 


I . RVB 














2 




2 


2 


2 


3 






2 


rO.WLB 








X 








X 










X 






lO.WVB 








2 


X 


X 




2 








2 


2 


X 




DEVICE-SPECIFIC FUNCTIONS 


10. ATA 


lO.ATTlTF.AST 


lO.CCO 


lO.WLBlTF.CCO 






















3 


X 






SF.GMC 
































10. GTS 
































lO.RAL 


IO.RLB!TF,RAL 
















X 


1 


X 








X 
X 
X 


lO.RNE 


lO.RLBlTF.RNE 












1 






1 


X 








10. RPR 






X 








1 




X 


1 


X 








lO.RST 


lO.RLBlTF.RST 












1 




X 




X 








X 


lO.RTT 












1 




X 




X 








X 




SF.SMC 
































lO.WAL 


lO.ViTLBITF.WAL 






3 








3 










3 






lO.WBT 


lO.WLBlTF.WBT 






X 








X 








3 









Exe 



rcise great care when using Read All and Read with Special Terminators together. Obscure problems can result. 



2. These subfunctions are allowed but are not effective. They are stripped off when the read or write virtual operation is 
converted to a read or write logical operation. 

3. During a write-pass-all operation (lO.WAL or 10. WLB! TF.WAL) the terminal driver outputs characters without 
interpretation; it does not keep track of cursor position. 
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2.3.2.1 10. ATA - 10. ATA is a variation of the Attach function. The 
use of this function is eased by the addition of TF.NOT and TF.XCC 
subfunction bits, described later in this section. 10. ATA specifies 
asynchronous system traps (ASTs) to process unsolicited input 
characters. When called as follows: 

QI0$C lO.ATA,.. . ,<[AST] , [PARAMETER2] [,AST2]> 

NOTE 

A minimum of one AST parameter (ast or 
ast2) is required. 

This function attaches the terminal and identifies "ast" and "ast2" as 
entry points for an unsolicited-input-character AST. Control passes 
to ast whenever an unsolicited character (other than CTRL/Q, CTRL/S, 
CTRL/X, or CTRL/0) is input. If the ast2 parameter is specified, an 
unsolicited CTRL/C character will result in entering the AST specified 
in that parameter. If ast2 is not specified, an unsolicited CTRL/C 
will result in entering the AST specified in the ast parameter. 

Unless the TF.XCC subfunction is specified, CTRL/C is trapped by the 
task and does not reach MCR. Thus, any task that uses 10. ATA without 
the TF.XCC subfunction should recognize some input sequence as a 
request to terminate; otherwise, MCR cannot be invoked to abort the 
task in case of difficulty. 

Note that either ast2 or TF.XCC can be used, but not both in the same 
QIO request. If both are specified in the request, an lE.SPC error is 
returned . 

Upon entry to the AST routines, the unsolicited character and 
parameter 2 are in the top word on the stack, as shown below. That 
word must be removed from the stack before exiting the AST. 

SP+10 Event flag mask word 

SP+06 PS of task prior to AST 

SP+04 PC of task prior to AST 

SP+02 Task's directive status word 

SP+00 Unsolicited character in low byte; parameter 2, in the 
high byte, is a user-specified value that can be used 
to identify individual terminals in a multiterminal 
environment 

The processing of unsolicited input ASTs is eased through the use of 
TF.NOT and TF.XCC subfunction bits. When TF.XCC is included in the 
10. ATA function, all characters (except CTRL/C) are handled in the 
manner previously described. CTRL/C marks the beginning of a command 
line interpreter (CLI) line that will be processed by a CLI task (for 
example, MCR); none of the characters, including the CTRL/C, are sent 
to the task issuing the function. 

When unsolicited terminal input (except CTRL/C) is received by the 
full-duplex terminal driver and the TF.NOT subfunction is used, the 
resulting AST serves only as notification of unsolicited terminal 
input; the terminal driver does not pass the character to the task. 
Upon entry to the AST service routine, the high byte of the first word 
on the stack identifies the terminal causing the AST (parameter 2). 
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After the AST has been effected, the AST becomes "disarmed" until a 
read request is issued by the task. If multiple characters are 
received before the read request is issued, they are stored in the 
type-ahead buffer. Once the read request is received, the contents of 
the type-ahead buffer, including the character causing the AST, is 
returned to the task; the AST is then "armed" again for new 
unsolicited input characters. Thus, using the TF.NOT subfunction 
allows a task to monitor more than one terminal for unsolicited input 
without the need to continuously read each terminal for possible 
unsolicited input. Note that the TF.NOT subfunction cannot be used 
with the CTRL/C AST; an unsolicited CTRL/C character flushes the 
type-ahead buffer. 

See the RSX-IlM/llM-PLUS Executive Reference Manual for further 
details on ASTs. 

10. ATA is equivalent to 10. ATT ORed with the subfunction bit TF.AST. 



2.3.2.2 lO.ATTlTF.ESQ - The task issuing this function attaches a 
terminal and notifies the driver that it recognizes escape sequences 
input from that terminal. Escape sequences are recognized only for 
solicited input. (See Section 2.6 for a discussion of escape 
sequences.) 

If the terminal has not been declared capable of generating escape 
sequences, lO.ATTiTF.ESQ has no effect other than attaching the 
terminal. No escape sequences are returned to the task because any 
ESC sent by the terminal acts as a line terminator. The SF.SMC 
function or the MCR SET /ESCSEQ command are used to declare the 
terminal capable of generating escape sequences (see Table 2-5 and 
Section 2.3.2.12) . 



2.3.2.3 lO.CCO - This write function directs the driver to write to 
the terminal regardless of a CTRL/0 condition that may be in effect. 
If CTRL/0 is in effect, it is cancelled before the write is done. 

10. ceo is equivalent to lO.WLBITF.CCO. 



2.3.2.4 SF.GMC - The Get Multiple Characteristics function returns 
terminal characteristics information, as follows: 

QIO$C SF.GMC,. ..,<stadd,size> 
St add 

The starting address of a data buffer of length "size" bytes. 
Each word in the buffer has the form 

.BYTE characteristic-name 
.BYTE 

characteristic-name 

One of the bit names given in Table 2-5. The value returned in 
the high byte of each byte-pair is 1 if the characteristic is 
true for the terminal and if it is not true. 

For the TC.TTP characteristic (terminal type), one of the values shown 
in Table 2-6 is returned in the high byte. 
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Table 2-5 
Full-Duplex Terminal Driver-Terminal Characteristics 
for SF.GMC and SF.SMC Functions 





Bit 
Name 


Octal 
Value 


Meaning (if asserted) 


Corresponding 
MCR Command 




TC.ABD 


11 


Auto-baud detection 


SET /ABAOD=TTnn: 




TC.ACR 


24 


Wrap-around mode 


SET /WRAP=TTnns 




TC.ANI 


122 


ANSI CRT terminal 






TC.ASPl 


76 


Remote line answer speed 


SET /REMOTE=TTnn: speed 


/ 


TC.AVO 


123 


VTlOO-family terminal display 




/ 


TC.BIN 


65 


Binary input mode (read-pass-all) 
no characters are interpreted 
as control characters. 


SET /RPA=TTnn: 




TC.BLK 


44 


Terminal is capable of block 
mode transfers 






TC.CTS 


72 


Suspend output to terminal 

= resume 

1 = suspend 


~~ 




TC.DEC 


124 


Digital CRT terminal 






TC.DLU4 


41 


Dial-up line 


SET /REMOTE=TTnn: 




TC . EDT 


125 


Terminal performs editing functions 






TC.EPA 


42 


When TC.PAR is enabled: 
O=odd parity 
l=even parity 


~*" 


V 


'tc.esq 


35 


Input escape sequence 

recognition 


SET /ESCSEQ=TTnn: 


y' 


TC . FDX 


64 


Full-duplex mode 


SET /FDX=TTnn: 


/ 


■'TC . HFF 


17 


Hardware form-feed capability 
(If 0, form-feeds are simulated 

using TC.LPP.) 


SET /FORMFEED=TTnn: 


TC.HFL 
/ 


13 


Number of fill characters to 

insert after a carriage return (0-7=x) 

(Use a value of 7 for the LA30-S.) 


SET /HFILL=TTnn:x 


V 


TC.HHT 


21 


Horizontal tab capability (if 0, 
horizontal tabs are simulated using 


SET /HHT=TTnn: 




r 

TO . HLD 1 




spaces.) 




v' 


44 


Hold screen mode 


SET /HOLD=TTnn: 




TC.ISL 


6 


Subline on interface (=0-15) (Read only) 


— 




TC.LPP 


2 


Page length (1-255. =x) 


SET /LINES=TTnn:x 



(continued on next page) 
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Table 2-5 (Cont.) 
Full-Duplex Terminal Driver-Terminal Characteristics 
for SF.GMC and SP.SMC Functions 



Bit 
Name 



TC.NBR 
TC.NEC 
TC . PAR 
TC.PRI 
TC . RAT 



TC . RGS 

TC.RSP2 
I^CSCP 

TC . SLV 
^C.SMR 

TC . TBF 

TC . TBS 
TC . TBM 



TC.TTP 

'TTC.VFL 

TC.WId3 
TC.XSP2 
TC.8BC 



Octal 
Value 



102 

47 

41 

51 

7 

126 

3 

12 
50 
25 

71 

100 
101 

10 

14 

1 

4 

67 



Meaning (if asserted) 



Broadcast disabled 

Echo suppressed 

Generate and check parity 

Terminal is privileged (Read only) 

Type-ahead buffer: 

= 1-character type-ahead 

1 = 36-character type-ahead 
(RSX-llM only) 

Terminal supports REGIS 
instructions 

Receiver speed (bits-per-second) 

Terminal is a scope (CRT) 

Terminal is a slave 

Upper-case conversion disabled 

Type-ahead buffer count (read) , 
or flush (write) 

Type-ahead buffer size (0-255=x) 
(RSX-llMPLUS only) 

Type- ahead buffer mode 
0=task typeahead 
1=CLI typeahead 
(RSX-llM-PLUS only) 

Terminal type (=0-255. =x) 

Send four fill characters after 
line feed 

Page width (=1-255. =x) 

Transmitter speed (bits-per-second) 

Pass eight bits on input, even 
if not binary input mode 
(TC.BIN) 



Corresponding 
MCR Command 



SET /NOBRO=TTnn: 
SET /ECHO=TTnn: 

SET /PRIV=TTnn: 

SET /TYPEAHEAD=TTnn: 



SET /SPEED=TTnn:rcv:xmit 
SET /CRT=TTnn: 
SET /SLAVE=TTnn: 
SET /LOWER=TTnn: 

SET /TYPEAHEAD=TTnn:x 



SET /x=TTnn: 
SET /TERM=TTnn:x 

SET /VFILL=TTnn: 



SET /BOF=TTnn:x 

SET /SPEED=TTnn:rcv:xmit 

SET /EBC=TTnn: 
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1. Effective for VT5x and VT61 only. 

2. TC.RSP, TC.XSP, TC.ASP and corresponding MCR SET /SPEED and SET /REMOTE 
command values for terminal receiver and transmitter speeds are listed below. 
(The valid combinations for each interface are in the RSX-llH/H-PLUS MCR 
Operations Manual. ) 



NOTE 



The MCR SET /SPEED command requires parameters for both receiver 
and transmitter (xmit) baud rates, as follows: 



(rev) 



SET /SPEED=TTnn; rev: xmit 



TC.ASP 
TC.RSP or 

TC.XSP Actual band rate (in bps) 
value and valid MCR SET /SPEED or SET /REMOTE 
values 



S.O 






(disabled) 


S.50 






50 


(Baudot codes are not 
supported) 


S.75 






75 




S.llO 






110 




S.134 






134 




S.150 






150 




S.200 






200 




S.300 






300 




S.600 






600 




S.1200 






1200 




S.1800 






1800 




S.2000 






2000 




S.2400 






2400 




S.3600 






3600 




S.4800 






4800 




S.7200 






7200 




S.9600 






9600 




S.EXTA 


(DHll 


external 


speed A) 




S . EXTB 


(DHll 


external 


speed B) 




S.19.2 






19200 





NOTE 

Speed can be set only on DHll and DZll controllers. DZll transmitter and 

receiver speeds must be equal (no split baud rates permitted). Only one 

value may be specified for the remote answer speed. This value applies 
to both the transmitter and receiver. 

3. Unsolicited input that fills the buffer before a terminator is received is 
likely invalid. When this happens, the driver discards the input by simulating 
a CTRL/0 and echoing "0. 

4. A program can enable the auto-call feature of the DF03 modem by setting 
TC.DLU to a value of two. (This is in addition to receiving incoming calls.) 
While in this mode, read and write requests are serviced even when a line is not 
in use. Consequently, I/O requests will not fail when the line is hung-up, 
which is the case for remote lines (TC.DL0=1) . 
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The TC.TTP Characteristic, when read by the terminal driver, sets 
implicit values for terminal characteristics TC.LPP, TC.WID, TC.HFF, 
TC.HHT, TC.VFL, and TC.SCP as shown in Table 2-6. These values can be 
changed (overridden) by subsequent Set Multiple Characteristics 
requests. In addition, TC.TTP is used by the terminal driver to 
determine cursor positioning commands, as appropriate. 

Table 2-6 
Bit TC.TTP (Terminal Type) Values Set by SF.SMC 
and Returned by SF.GMC 



Octal 




Terminal 
Type 




Implicit 


Character! St ics^ 


Value 1 


Symbolic 


TC.LFP 


TC.WID 


TC.HFF 


TC.HHT 


TC.HFL 


TC.VFL 


TC.SCP 





T.UNKO 


Unknown 
















1 


T.AS33 


ASR33 


66 


72 






1 






2 


T.KS33 


KSR33 


68 


72 






1 






3 


T.AS35 


ASR35 


66 


72 






1 






4 


T.L30S 


LA30S 


66 


80 






7 






5 


T.L30P 


LA30P 


66 


80 












6 


T.LA36 


LA36 


66 


132 












7 


T.VT05 


VT05 


20 


72 




1 




1 


1 


10 


T.VT50 


VT50 


12 


80 




1 






1 


11 


T.VT52 


VT52 


24 


80 




1 






1 


12 


T.VT55 


VT55 


24 


80 




1 






1 


13 


T.VT61 


VT61 


24 


80 




1 






1 


14 


T.L180 


LA180S 


66 


132 


1 










15 


T.VlOO 


VTIOO 


24 


80 




1 






1 


16 


1.1,120 


LA120 


66 


132 


1 










20 


T.LA12 


LA12 


66 


132 


1 


1 








21 


T.LIOO 


LAI 00 


66 


132 


1 


1 








22 


T.LA34 


LA34 


66 


132 




1 








23 


T.LA38 


LA38 


66 


132 




1 








24 


T.VIOI 


VTlOl 


24 


80 




1 








25 


T.V102 


VT102 


24 


80 




1 








26 


T.V105 


VT105 


24 


80 




1 








27 


T.V125 


VT125 


24 


80 




1 








30 


T.V131 


VT131 


24 


80 




1 








31 


T.V132 


VT132 


24 


80 




1 








32 


T.LA50 


LA50 


60 


80 


1 


1 








33 


T.LQPl 


LQPOl 


66 


132 


1 


1 








34 


T.LQP2 


LQP02 


66 


132 


1 


1 









1. Octal values 0-177 are reserved by DIGITAL, 
customer use to define non-DIGITAL terminals. 



Values 200-377 are available for 



2. Implicit characteristics are shown as supported by the driver. Values not shown 
are not automatically set by the driver. An "unknown" terminal type has no 
implicit characteristics. 

The TC.CTS characteristic returns the present suspend (CTRL/S) , resume 
(CTRL/Q) , or suppress (CTRL/0) state set via the SF.SMC function. 
Values returned are as follows: 



Valae 
Returned 



State 



Resume (CTRL/Q) 

Suspend (CTRL/S) 

Suppress (CTRL/0) 

Both suppress and suspend 
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When a value of is used with the SF.SMC function, the suspend state 
is cleared; a value of 1 selects the suspend state. 

The TC.TBF characteristic returns the number of unprocessed characters 
in the type-ahead buffer for the specified terminal. This allows 
tasks to determine if any characters were typed that did not require 
AST processing. In addition, the value returned can be used to read 
the exact number of characters typed, rather than a typical value of 
80. or 132. characters for the terminal. 



NOTES 



1. It is necessary that the task attach 
the terminal to receive characters 
from the type-ahead buffer. 

2. The maximum capacity of the 
type-ahead buffer is 36. characters 
for RSX-llM systems and 255. 
characters for RSX-llM-PLUS systems. 

3. Using TC.TBF in an SF.SMC function 
will flush the type-ahead buffer. 



2.3.2.5 10. GTS - This function is a Get Terminal Support request that 
returns information to a 4-word buffer specifying which SYSGEN-option 
features are part of the terminal driver. Only two of these words are 
currently defined. Table 2-7 gives details for these words. The 
10. GTS function is a SYSGEN option. If 10. GTS is issued on a system 
without 10. GTS support, lE.IFC is returned in the I/O status block. 

The various symbols used by the 10. GTS, SF.GMC, and SF.SMC functions 
are defined in a system module, TTSYM. These symbols include: Fl.xxx 
and F2.XXX (Table 2-7); T.xxxx (Table 2-6); TC.xxx (Table 2-5); and 
the SE.xxx error returns described in Table 2-8, Section 2.4. These 
symbols may be defined locally within a code module by using: 

.MCALL TTSYM$ 



TTSyM$ 

Symbols that are not defined locally are automatically defined by the 
Task Builder. 

Octal values shown for the symbols are subject to change. Therefore, 
it is recommended that only the symbolic names be used. 
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Table 2-7 
Information Returned by Get Terminal Support (10. GTS) QIO 





Octal 








Bit 


Value 


Mnemonic 


Meaning When Set to 1 




Word 


of BuJ 


Efer: 









1 


Fl.ACR 
Fl.BTWl 


Automatic CR/LF on long lines 




1 


2 


Break-through write 




2 


4 


Fl.BUF 
Fl.UIA^ 


Checkpointing during terminal input 




3 


10 


Unsolicited-input-character AST 




4 


20 


Fl.CCO 


Cancel CTRL/0 before writing 




5 


40 


fi.esqI 


Recognize escape sequences in solici 
input 


ted 


6 


100 


Fl.HLD 


Hold-screen mode 




7 


200 


Fl.LWcl 


Lower- to uppercase conversion 




8 


400 


Fl.RNE 


Read with no echo 




9 


1000 


fi.rprI 


Read after prompting 




10 


2000 


Fl.RST 


Read with special terminators 




11 


4000 


fi.rubI 


CRT rubout 




12 


10000 


Fl.SYN 


CTRL/R terminal synchronization 




13 


20000 


Fl . TRW 


Read all and write all 




14 


40000 


Fl.UTB 


Input characters buffered in task's 
address space 




15 


100000 


Fl.VBF 


Variable-length terminal buffers 




Word 


1 of BuJ 


:fer : 









1 


F2.SCh1 
F2.GCh1 


Set characteristics QIO (SF.SMC) 




1 


2 


Get characteristics QIO (SF.GMC) 




5 


40 


F2.SFF 


Formfeed can be simulated 




fi 


100 


F2.CUpl 


Cursor positioning 




7 


200 


F2.FDX 


Full Duplex Terminal Driver 





1. SYSGEN options on RSX-llM systems. 



2.3.2.6 lO.RAL - The Read All function causes the driver to pass all 
bits to the requesting task. The driver does not intercept control 
characters or mask out the "parity" (high-order) bit. For example, 
CTRL/C, CTRL/Q, CTRL/S, CTRL/0, and CTRL/Z are passed to the program 
and are not interpreted by the driver. 



NOTE 

lO.RAL echoes the characters that are 
read. The terminal driver in Version 2 
of RSX-llM did not echo a Read All. To 
read all bits without echoing, use 
lO.RALlTF.RNE. 



lO.RAL is equivalent to lO.RLB ORed with the subfunction bit TF.RAL. 
The lO.RAL function can be terminated only by a full character count 
(input buffer full) . 
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2.3.2.7 lO.RNE - The lO.RNE function reads terminal input characters 
without echoing the characters back to the terminal for immediate 
display. This feature can be used when typing sensitive information 
(for example, a password or combination) or when reading a badge with 
the RT02-C terminal. 

(Note that the no-echo mode can also be selected with the SF.SMC 
function; see Table 2-5, bit TC.NEC.) 

CTRL/R is ignored while an lO.RNE is in progress. 

The lO.RNE function is equivalent to 10. RLE ORed with the subfunction 
bit TF.RNE. 



2.3.2.8 10. RPR - The 10. RPR Read After Prompt functions as an lO.WLB 
(to write a prompt to the terminal) followed by 10. RLE. However, 
10. RPR differs from this combination of functions as follows: 

• System overhead is lower with the 10. RPR because only one QIO 
is processed. 

• When using the 10. RPR function, there is no "window" during 
which a response to the prompt may be ignored. Such a window 
occurs if IO.WAL/IO.R1.B is used, because no read may be posted 
at the time the response is received. 

• If the issuing task is checkpointable, it can be checkpointed 
during both the prompt and the read requested by the 10. RPR. 

• A CTRL/0 that may be in effect prior to issuing the 10. RPR is 
canceled before the prompt is written. 

Subfunction bits may be ORed with 10. RPR to write the prompt as a 

Write All (TF.BIN) and to send XOFF after the read (TF.XOF). In 

addition, read subfunction bits TF.RAL, TF.RNE, and TF.RST can be used 
with 10, RPR. 



NOTE 

If an 10. RPR function is in progress 
when the driver receives a CTRL/R or 
CTRL/U, the prompt is redisplayed. 



2.3.2.9 IO.RPRITE.BIN - This function results in a read after a 
"binary" prompt; that is, a prompt is written by the driver with no 
character interpretation (as if it were issued as an lO.WAL) . 



2.3.2.10 lO.RPRITE.XOF - This function causes the driver to send an 
XOFF to the terminal after its prompt-and-read. The XOFF or CTRL/S 
may have the effect of inhibiting input from the terminal, if the 
terminal recognizes XOFF for this purpose. TF.XOF is ignored when 
full-duplex I/O is in use. 
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2.3.2.11 lO.RST - This function is similar to an lO.RLB, except 
certain special characters terminate the read. These characters are 
in the ranges 0-037 and 175-177. The driver does not interpret the 
terminating character, with certain exceptions.! For example, a 
horizontal TAB (Oil) is not expanded, a RUBOUT (or DEL, 177) does not 
erase, and a CTRL/C does not produce an MCR prompt. 

Upon successful completion of an lO.RST request that was not 
terminated by filling the input buffer, the first word of the I/O 
status block contains the terminating character in the high byte and 
the IS. sue status code in the low byte. The second word contains the 
number of bytes contained in a buffer. The terminating character is 
not put in the buffer. 



lO.RST is equivalent to lO.RLBiTF.RST. 



2.3.2.12 SF.SMC - This function enables a task to set and reset the 
characteristics of a terminal. Set Multiple Characteristics is the 
inverse function of SF.GMC. Like SF.GMC, it is called in the 
following way: 

QIO$C SF.SMC, ... ,<stadd,size> 

stadd 

The starting address of a buffer of length "size" bytes. Each 
word in the buffer has the form 

.BYTE characteristic-name 
.BYTE value 

characteristic-name 

One of the symbolic bit names given in Table 2-5. 

value 

Either (to clear a given characteristic) or 1 (to set a 
characteristic) . 

Table 2-5 notes the restrictions that apply to these characteristics. 

If the characteristic-name is TC.TTP (terminal type) , value can have 
any of the values listed in Table 2-6. 

A nonprivileged task can only issue an SF.SMC request for its own 
terminal (TI:). A privileged task can issue SF.SMC to any terminal. 

Terminal output can be suspended or resumed (simulated CTRL/S and 
CTRL/Q, respectively) by specifying an appropriate value for TC.CTS. 
A value of resumes output and a value of 1 suspends output. 



1. If upper- to lowercase conversion is disabled, characters 175 and 
176 do not act as terminators. CTRL/0, CTRL/Q, and CTRL/S (017, 021, 
and 023, respectively) are not special terminators. The driver 
interprets them as output control characters in a normal manner. 



2-21 



FULL-DUPLEX TERMINAL DRIVER 

Specifying any value for TC.TBF flushes (clears) the type-ahead buffer 
(forces the type-ahead buffer count to 0). 



2.3.2.13 lO.RTT - This QIO function reads characters in a manner like 
the lO.RLB function, except a user-specified character terminates the 
read operation. The specified character's code can range from 0-377. 
It is user designated by setting the appropriate bit in a 16-word 
table that corresponds to the desired character. Multiple characters 
can be specified by setting their corresponding bits. 

The 16-word table starts at the address specified by the table 
parameter. The first word contains bits that represent the first 16 
ASCII character codes (0-17) ; similarly, the second word contains 
bits that represent the next 16 character codes (20-37), and so forth, 
through the sixteenth word, bit 15, which represents character code 
377. For example, to specify the % symbol (code 045) as a read 
terminator character, set bit 05 in the third word, since the third 
word of the table contains bits representing character codes 40-57. 

If the CTRL/S (023) , CTRL/Q (021) , and/or any characters whose codes 
are greater than 177 is/are desired as the terminator character (s) , 
the terminal must be set to read-pass-all operation (TC.BIN=1), or 
read-pass 8-bits (TC.8BC) , as listed in Table 2-5. 

The optional time-out count parameter can be included, as desired. 



2.3.2.14 lO.WAL - The Write All function causes the driver to pass 
all output from the buffer without interpretation. It does not 
intercept control characters. Long lines are not wrapped around if 
input/output wrap-around has been selected. 

lO.WAL is equivalent to the lO.WLB! TF.WAL function. 



2.3.2.15 lO.WBT - The lO.WBT function instructs the driver to write 
the buffer regardless of the I/O status of the receiving terminal. If 
an lO.WBT function is issued on a system that does not support 10. WET, 
it is treated as an lO.WLB function. 

• If another write function is currently in progress, it 
finishes the current request and the lO.WBT is the next write 
issued. The effect of this is that a CTRL/S can stop lO.WBT 
functions. Therefore, it may be desirable for tasks to time 
out on lO.WBT operations. 

• If a read is currently posted, the lO.WBT proceeds, and an 
automatic CTRL/R is performed to redisplay any input that was 
received before the break-through write was effected (if the 
terminal is not in the full-duplex mode) . 

• CTRL/O, if in effect, is canceled. 

• An escape sequence that was interrupted is rubbed out. 

An lO.WBT function cannot break through another lO.WBT that is in 
progress. 

Break-through write may only be issued by a privileged task. The 
privileged MCR command BRO (broadcast) uses lO.WBT. 
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2.3.2.16 lO.HNG - The lO.HNG function disconnects a terminal that 
on a remote line. This function has no arguments. 



IS 



A nonprivileged task can only issue an lO.HNG request for its own 
terminal (TI:). A privileged task can issue lO.HNG to any terminal. 



2.4 STATUS RETURNS 

Table 2-8 lists error and status conditions that are returned by 
terminal driver to the I/O status block. 



the 



Most RSX-llM error and status codes returned are byte values. For 
example, the value for IS.SUC is 1. However, IS.CC, IS.CR, IS. ESC, 
and IS. ESQ are word values. When any of these codes are returned, the 
low byte indicates successful completion, and the high byte shows what 
type of completion occurred. 

To test for one of these word-value return codes, first test the low 
byte of the first word of the I/O status block for the value IS.SUC. 
Then, test the full word for IS.CC, IS.CR, IS, ESC, or IS. ESQ. (If the 
full word tests equal to IS.SUC, then its high byte is 0, indicating 
byte-count termination of the read.) 

The "error" return IE. EOF may be considered a successful read since 
characters returned to the task's buffer can be terminated by a CTRL/Z 
character. 

The SE.xxx codes are returned by the SF.GMC and SF.SMC functions as 
described in Sections 2.3.2.4 and 2.3.2.12. When any of these codes 
are returned, the low byte in the first word in the I/O status block 
will contain IE. ABO. The second lOSB word contains an offset 
(starting from 0) to the byte in error in the QIO's stadd buffer. 



Table 2-8 
Terminal Status Returns 



Code 



IE. EOF 



IS.SUC 



Reason 



Successful completion on a read with end-of-file 

The line of input read from the terminal was 
terminated with the end-of-file character CTRL/Z. 
The second word of the I/O status block contains the 
number of bytes read before CTRL/Z was seen. The 
input buffer contains those bytes. 

Successful completion 

The operation specified in the QIO directive was 
completed successfully. If the operation involved 
reading or writing, you can examine the second word 
of the I/O status block to determine the number of 
bytes processed. The input buffer contains those 
bytes. 



vContinueu on next page) 



2-23 



Code 



IS.CC 



IS.CR 



IS. ESC 



IS. ESQ 



IS.PND 



IS.TMO 



IE. ABO 



IE. BAD 



lE.BCC 
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Table 2-8 (Cont.) 
Terminal Status Returns 



Reason 



Successful completion on a read 

The line of input read from the terminal was 
terminated by a CTRL/C. The input buffer contains 
the bytes read. 

Successful completion on a read 

The line of input read from the terminal was 
terminated by a carriage return. The input buffer 
contains the bytes read. 

Successful completion on a read 

The line of input read from the terminal was 
terminated by an Altmode character. The input buffer 
contains the bytes read. 

Successful completion on a read 

The line of input read from the terminal was 
terminated by an escape sequence. The input buffer 
contains the bytes read and the escape sequence. 

I/O request pending 

The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 

Successful completion on a read 

The line of input read from the terminal was 
terminated by a time-out (TF.TMO was set and the 
specified time interval was exceeded) . The input 
buffer contains the bytes read. 

Operation aborted 

The specified I/O operation was cancelled by lO.KIL 
while in progress or while in the I/O queue. The 
second word of the I/O status block indicates the 
number of bytes that were put in the buffer before 
the kill was effected. 

Bad parameter 

The size of the buffer exceeds 8128 bytes. 

Framing error 

A framing error was hardware-detected and returned by 
the controller. All characters up to (but not 
including) the erroneous character are in the buffer. 
This condition can result by pressing the BREAK key 
on some terminals, or by hardware problems. 



(continued on next page) 
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Table 2-8 (Cont.) 
Terminal Status Returns 



Reason 



lE.DAA Device already attached 

The physical device unit specified in an 10. ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has already 
attached the desired physical device unit, not that 
the unit was attached by another task. If the attach 
specified TF.AST or TF.ESQ, these subfunction bits 
have no effect. 

lE.DAO Data overrun error 

A data overrun error was hardware-detected and 
returned by the controller. All characters up to 
(but not including) the erroneous character are in 
the buffer. This error occurs when a hardware 
failure or incompatibility causes characters to be 
received by the controller faster than they can be 
processed (that is, an incorrect serial I/O baud rate 
or format exists) . 

lE.DNA Device not attached 

The physical device unit specified in an lO.DET 
function was not attached by the issuing task. This 
code has no bearing on the attachment status of other 
tasks. 

lE.DNR Device not ready 

The physical device unit specified in the QIO 

directive was not ready to perform the desired I/O 

operation. This code is returned to indicate one of 
the following conditions: 

• A time-out occurred on the physical device unit 
(that is, an interrupt was lost) . 

• An attempt was made to perform a function on a 
remote DHll or DZll line without carrier present. 



lE.IES 



Invalid escape sequence 

An escape sequence was started but escape-sequence 
syntax was violated before the sequence was 
completed. (See Section 2.6.4.) The character 
causing the violation is the last character in the 
buffer. 



lE.IFC 



Illegal function 

A function code specified in an I/O request was 

illegal for terminals; or, the function code 

speciEiea was <a DiovjrjJN opi-j.on nui- 
system. 



Lecte 



i-orl f (-! r this 



(continued on next page) 
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Table 2-8 (Cont.) 
Terminal Status Returns 



Code 



Reason 



IE. NOD 



Buffer allocation failure 



lE.OFL 



System dynamic storage has been depleted resulting in 
insufficient space available to allocate an 
intermediate buffer for an input request or an AST 
block for an attach request. 

Device off line 



IE. PES 



The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. In RSX-llM-PLUS systems, the physical 
device unit could have been configured off line. 

Partial escape sequence 

An escape sequence was started, but read-buffer space 
was exhausted before the sequence was completed. See 
Section 2.6.4.3. 



lE.PRI Privilege violation 

In a multiuser system, a nonprivileged task issued an 
lO.WBT, directed an SF.SMC to a terminal other than 
TI:, or it attempted to set its privilege bit. 

lE.SPC Illegal address space 

The buffer specified for a read or write request was 

partially or totally outside the address space of the 

issuing task, a byte count of was specified, or an 
odd or AST address was specified. 

lE.VER Character parity error 

A parity error was hardware-detected and returned by 
the controller. All characters up to (but not 
including) the erroneous character are in the buffer. 

SE.NIH A terminal characteristic other than those in Table 
2-5 was named in an SF.GMC or SF.SMC request, or a 
task attempted to assert TC.PRI. 

SE.FIX An attempt was made to change a fixed characteristic 
in a SF.SMC subfunction request (for example, an 
attempt was made to change the unit number) . 

SE.VAL The new value specified in an SF.SMC request for the 
TC.TTP terminal characteristic was not one of those 
listed in Table 2-6. 



(continued on next page) 
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Table 2-8 (Cont.) 
Terminal Status Returns 



Code 



SE.NSC 



SE.SPD 



Reason 



An attempt was made to change a nonsettable 
characteristic. This error can occur when an attempt 
is made to make a local-only line a remote line when 
the controller does not support remote lines, or when 
no remote line support was specified during SYSGEN. 

The new speed specified in an SF.SMC subfunction 
request was not valid for the controller associated 
with the specified terminal. 



2.5 CONTROL CHARACTERS AND SPECIAL KEYS 

This section describes the meanings of special terminal control 
characters and keys for RSX-llM. Note that the driver does not 
recognize control characters and special keys during a Read All 
request (lO.RAL) , and recognizes only some of them during a Read with 
Special Terminators (lO.RST) . 



2.5.1 Control Characters 

A control character is input from a terminal by holding the control 
key (CTRL) down while typing one other key. Three of the control 
characters described in Table 2-9, CTRL/R, CTRL/U, and CTRL/Z , are 
echoed on the terminal as "R, 'U, and "Z, respectively. 



Table 2-9 
Terminal Control Characters 



Character 



CTRL/C 



Meaning 



Typing CTRL/C causes unsolicited input on that 
terminal to be directed to a control line interpreter 
task, such as MCR. (Command line interpreters are 
invoked and display a prompt in a manner similar to 
that of MCR; therefore, for the purposes of this 
discussion, it is assumed that MCR is the command 
line interpreter in use, although the terminal driver 
will respond to other command line interpreters in a 
similar manner.) The "MCR>" prompt is echoed when the 
terminal driver is ready to accept an unsolicited MCR 
command line for input. When the unsolicited input 
is terminated, the command line is passed to MCR. 

If the last character typed on the terminal was a 
CTRL/S (suspend output) , CTRL/C restarts suspended 
output and directs subsequent input to MCR. 

selected and the terminal is a VT5x or VT61 in 
hold-screen mode, typing a CTRL/C removes the 
terminal from hold-screen mode. 



(continued on next page) 
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Table 2-9 (Cont.) 
Terminal Control Characters 



Character 



Meaning 



CTRL/I 

CTRL/ J 
CTRL/K 

CTRL/L 



CTRL/M 
CTRL/0 



CTRL/Q 



CTRL/C characters can also be directed to a task if 
the task has attached a terminal and has specified an 
unsolicited-input-character AST (see Section 
2.3.2.1). CTRL/C characters are also passed to a 
task if an lO.RAL or lO.RST function is effected. 



NOTE 

If the terminal driver receives a CTRL/C 
character during a read operation (except 
during a Read-Pass-All operation or a Read 
With Special Terminators operation) , the read 
operation is terminated, the type-ahead 
buffer is cleared, and an IS.CC status code 
is returned to the task. 



CTRL/I or TAB characters initiate a horizontal tab, 
and the terminal spaces to the next tab stop. Tabs 
at every eighth character position are simulated by 
the terminal driver. 

CTRL/J is equivalent to a LINE FEED character. 

CTRL/K initiates a vertical tab, and the terminal 
tabs to the next vertical tab stop. For a CRT 
terminal, four LINE FEEDs are output. 

CTRL/L initiates a formfeed. If the terminal has 

hardware formfeed support, the driver echos "L. 

Otherwise, the driver simulates the formfeed by 

outputting enough LINE FEED characters to advance the 
next character position to the top of the next page. 

If a CRT terminal is in use, four LINE FEEDs are 
output. 

CTRL/M is equivalent to a carriage RETURN character 
(see Section 2.5.2) . 

CTRL/0 suppresses terminal output. For attached 
terminals, CTRL/0 remains in effect (output is 
suppressed) until one of the following occurs: 

• The terminal is detached. 

• Another CTRL/0 character is typed, 

• An 10. ceo or lO.WBT function is issued. 

• Input is entered. 

For unattached terminals, CTRL/0 suppresses output 
for only the current output buffer (typically one 
line) . 

CTRL/Q resumes terminal output previously suspended 
by means of CTRL/S. 



(continued on next page) 
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Table 2-9 (Cont.) 
Terminal Control Characters 



Character 



CTRL/S 
CTRL/R 



CTRL/U 

CTRL/X 
CTRL/Z 



Meaning 



CTRL/S suspends terminal output. (Output 
resumed by typing CTRL/Q or CTRL/C.) 



can be 



CTRL/R response is a terminal driver feature that can 
be selected during RSX-llM V3.2 SYSGEN. _ Typing 
CTRL/R results in a carriage return and line feed 
being echoed, followed by the incomplete 
(unprocessed) input line. Any tabs that were input 
are' expanded and the effect of any rubouts is shown. 
On hardcopy terminals, CTRL/R allows verifying the 
effect of tabs and/or rubouts in an input line. 
CTRL/R is also useful for CRT terminals when the CRT 
rubout SYSGEN option has been selected (see Section 
2.8). For example, after rubbing out the left-most 
character on the second displayed line of a wrapped 
input line, the cursor does not move to the right of 
the first displayed line. In this case, CTRL/R 
brings the input line and the cursor back together 
again. 

Typing CTRL/U before typing a line terminator deletes 
previously typed characters back to the beginning of 
the line. The system echoes this character as "U 
followed by a carriage return and a line feed. 

This character clears the type-ahead buffer. 

CTRL/Z indicates an end-of-file for the current 
terminal input. It signals MAC, PIP, TKB, and other 
system tasks that terminal input is complete, 
allowing the task to exit. The system echoes this 
character as 'Z, followed by a carriage return and a 
line feed. 



2.5.2 Special Keys 

The Escape, carriage RETURN, and RUBOUT keys have special significance 
for terminal input, as described in Table 2-10. A line can be 
terminated by an ESCape (or Altmode) , carriage RETURN, or CTRL/Z 
characters, or by completely filling the input buffer (that is, by 
exhausting the byte count before a line terminator is typed). The 
standard buffer size for a terminal can be determined for a task by 
issuing a Get LUN Information system directive and examining Word 5 of 
the buffer. An operator can obtain the same information with the MCR 
SET /BUF=TI : command. 



2.6 ESCAPE SEQUENCES 

„ , ™*- — i-^ — ^ «^ +-».T^ ^v TTi^va r^Vi a Kar>^- or Q hpn 1 nn 1 nd with 

Escape sequences die ai-rj-ng^ u j. ui»w \j i. 111^...^ ^.^^^ «v- _v-. ^ — ^ ^ 

an ESC (033) character. In RSX-llM systems, escape sequence support 
described in this section is a SYSGEN option. Some terminals generate 
an escape sequence when a special key is pressed (for example, the FCN 
key on the VTfil) . On any terminal, an escape sequence may^ be 
generated manually by typing ESCape followed by the appropriate 
characters. 
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Escape sequences provide a way to pass input to a task without 
interpretation by the operating system. This could be done with a 
number 1-character Read All functions, but escape sequences allow them 
to be read with lO.RLB requests. 



Table 2-10 
Special Terminal Keys 



Key 



Escape 



RETURN 



RUBOUT 



Meaning 



If escape sequences are not recognized, typing ESCape 
or Altmode signals the terminal driver that there is 
no 'further input on the current line. This line 
terminator allows further input on the same line, 
because the carriage or cursor is not returned to the 
first column position. 

If escape sequences are recognized, ESCape signals 
the beginning of an escape sequence. (See Section 
2.6.) 

Typing RETURN terminates the current line and causes 
the carriage or cursor to return to the first column 
on the line. 

Typing RUBOUT deletes the last character typed on an 
input line. Only characters typed since the last 
line terminator may be deleted. Several characters 
can be deleted in sequence by typing successive 
RUBOUTs. 

For example, on a printing terminal, the first RUBOUT 
echoes a backslash (\) followed by the character that 
has been deleted, even if the terminal is in the 
no-echo mode. Subsequent RUBOUTs cause only the 
deleted character to be echoed. The next character 
typed that is not a RUBOUT causes another backslash 
to be printed, followed by the new character. The 
non-RUBOUT character will not be echoed if the 
terminal is in the no-echo mode; however, a 
backslash is echoed in response to the first 
non-RUBOUT character. The following example 
illustrates rubbing out ABC and then typing CBA: 

ABC\CBA\CBA 

The second backslash is not displayed if a line 
terminator is typed after rubbing out the characters 
on a line, as in the following example: 

ABC\CBA 

At SYSGEN time, the "CRT rubout" feature can be 
selected. This feature applies to a terminal only 
after a SET MCR directive has been issued: 

SET /CRT=TI: 



[continued on next page) 
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Table 2-10 (Cont.) 
Special Terminal Keys 



Key 



Meaning 



If the CRT rubout feature was selected, RUBOUT causes 
the last typed character (if any) to be removed from 
the incomplete input line and a 
backspace-space-backspace sequence of characters for 
that terminal are echoed. If the last typed 
character was a tab, enough backspaces are issued to 
move the cursor to the character position before the 
tab v/as typed. If a long input line was split, or 
"wrapped," by the automatic-carriage-return option, 
and a RUBOUT erases the last character of a previous 
line, the cursor is not moved to the previous line. 
CTRL/R must be used to resynchronize the current, 
display with the contents of the incomplete input 
line. 



2.6.1 Definition 

The format of an escape sequence as defined in 
Standard X 3.41— 1974 and used in the VTIOO is: 



American National 



ESC 



ESC 



The introducer control character (33(8)) that is named escape. 



that may or may not be 
combination 40(8) to 57(8) 
inclusive in both 7- and 8-bit environments. 



The intermediate bit combinations 
present. I characters are bit 



The final character. F characters are bit combinations 60(8) 
to 176(8) inclusive in escape sequences in both 7- and 8-bit 
environments. 



The occurrence of characters in the inclusive ranges 0(8) to 37(8) 
is technically an error condition whose recovery is to execute 
immediately the function specified by the character and then 
continue with the escape sequence execution. The exceptions are: 
if the character ESC occurs, the current escape sequence is aborted, 
and a new one commences, beginning with the ESC just received; if 
the character CAN (30(8)) or the character SUB (32(8)) occurs, the 
current escape sequence is aborted, as is the case with any control 
character. 



There are five exceptions to this general definition; 
exceptions are discussed in Section 2.6.5. 



these 
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2.6.2 Prerequisites 



Two prerequisites must be satisfied before escape sequences can be 

received by a task. 

First, the task must "ask" for them by issuing an 10. ATT function 
and invoking the subfunction bit TF.ESQ. 

Second, the terminal must be declared capable of generating escape 
sequences. This may be done with an MCR SET command: 

SET /ESCSEQ=TI: 

An alternative way to tell the driver that the terminal can generate 
escape sequences is by issuing the Set Multiple Characteristics 
request. (See Section 2.3.2.12). 

If either of these prerequisites is not satisfied, the ESC character 
is treated as a line terminator. 

If both prerequisites are satisfied, CTRL/SHIFT/0 (037) may be used as 
an Altmode character. 1 This character does not act as an Altmode from 
a terminal that cannot generate escape sequences. 



2.6.3 Characteristics 

Escape sequences always act as line terminators. That is, an input 
buffer may contain other characters that are not part of an escape 
sequence, but an escape sequence always comprises the last characters 
in the buffer. 

Escape sequences are not echoed. However, if a non-CRT rubout 
sequence is in progress, it is closed with a backslash when an escape 
sequence is begun. 

Escape sequences are not recognized in unsolicited input streams. 
Neither are they recognized in a Read with Special Terminators 
(subfunction bit TF.RST) nor in a Read All (subfunction bit TF.RAL) . 



2.6.4 Escape Sequence Syntax Violations 

A violation of the syntax defined in Section 2.6.1 causes the driver 
to abandon the escape sequence and to return an error (lE.IES). 



2.6.4.1 DEL or RUBOUT (177) - The character DEL or RUBOUT is not 
legal within an escape sequence. Typing it at any point within an 
escape sequence causes the entire sequence to be abandoned and deleted 
from the input buffer. Thus, use DEL or RUBOUT to abandon an escape 
sequence, if desired, once you have begun it. 



1. An Altmode is a line terminator that does not cause the cursor to 
advance to a new line. On terminals that cannot generate escape 
sequences, the ESCape key acts as an Altmode. Characters 175 and 176 
also function as Altmodes if the terminal has not been declared 
lowercase (MCR command SET /LOWER) . 
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2.6.4.2 Control Characters (0-037) - The reception of any character 
in the range to 037 (with four exceptions — see footnotel) is a 
syntax violation that terminates the read with an error (lE.IES). 



2.6.4.3 Full Buffer - A syntax error results when an escape sequence 
is terminated by running out of read-buffer space, rather than by 
receipt of a final character. The error IE. PES is returned. For 
example, after a task issues an lO.RLB with a buffer length of 2, and 
you type: 

ESC ! A 

the buffer contains "ESC I", and the I/O status block contains: 

lose 



IE. PES 



The "A" is treated as unsolicited input. 



2.6.5 Exceptions to Escape-Sequence Syntax 

Five "final characters" that normally terminate an escape sequence are 
treated as special cases by the terminal driver for use with certain 
terminals: 



ESC 


?... 


ESC 


0... 


ESC 


P. .. 


ESC 


Y. .. 


ESC 


[... 



Refer to documentation supplied with the specific terminal (s) 
for correct use of escape sequences. 



in use 



2.7 VERTICAL FORMAT CONTROL 

Table 2-11 is a summary of all characters used for vertical format 

control on the terminal. Any one of these characters can be specified 

as the value of the vfc parameter in lO.WLB, lO.WVB, lO.WBT, lO.CCO, 
or 10. RPR functions. 



1. Four control characters are allowed: CTRL/Q, CTRL/S, CTRL/X, and 
CTRL/0. These characters are handled normally by the operating system 
even when an escape sequence is in progress. For example, entering: 



ESC CTRL/S A 



gives: 



lOSB 



IS. ESQ 



with the additional effect of turning off the output stream. 
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2.8 AUTOMATIC CARRIAGE RETURN 

Individual terminals can be set for wrap-around, as desired, using the 
MCR SET command 

>SET /WRAP=TTxx: 

Once wrap-around has been selected, the column at which wrap-around 
occurs can be selected using the MCR SET command 

>SET /BUF=TI:n 
> 

The SET /BUF command can also be used without an argument to display 
the current buffer width for a terminal: 

>SET /BUF=TI: 
BUF=TI: 00072. 
> 



Table 2-11 
Vertical Format Control Characters 



Octal 
Value 



040 



060 



Character 



blank 



061 



053 



044 



000 



null 



Meaning 



SINGLE SPACE - Output one line feed, print the 
contents of the buffer, and output a carriage 
return. Normally, printing immediately follows 
the previously printed line. 

DOUBLE SPACE - Output two line feeds, print the 
contents of the buffer, and output a carriage 
return. Normally, the buffer contents are 
printed two lines below the previously printed 
line. 

PAGE EJECT - If the terminal supports FORM 
FEEDS, output a form feed, print the contents of 
the buffer, and output a carriage return. If 
the terminal does not support FORM FEEDs, the 
driver simulates the FORM FEED character by 
either outputting four line feeds to a crt 
terminal, or by outputting enough line feeds to 
advance the paper to the top of the next page on 
a printing terminal. 

OVERPRINT - Print the contents of the buffer and 
output a carriage return, normally overprinting 
the previous line. 

PROMPTING OUTPUT - Output one line feed and 
print the contents of the buffer. This mode of 
output is intended for use with a terminal on 
which a prompting message is output, and input 
is then read on the same line. 

INTERNAL VERTICAL FORMAT - Print the buffer 
contents without addition of vertical format 
control characters. In this mode, more than one 
line of guaranteed contiguous output can be 
printed for each I/O request. 
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All other vertical format control characters are interpreted as blanks 
(040) . 

A task can determine the buffer width by issuing a Get LUN Information 
directive and examining word 5 returned in the buffer. 

After the SET has been done, typing beyond the buffer width results in 
a carriage return and line feed being output before the next character 
is echoed. Although only one line only was input, it is displayed on 
two terminal lines. 

It is possible to lose track of where you are in the input buffer if 
wrap-around is enabled for your terminal. For example, while deleting 
text on a wrapped line, the cursor will not back up to the previous 
line. In order to resynchronize the cursor with the contents of the 
incomplete input buffer, type CTRL/R (if this SYSGEN option has been 
selected) . 



2.9 FEATURES AVAILABLE BY RSX-llM SYSGEN OPTION 

A number of terminal-driver features are available as RSX-llM SYSGEN 
options. (See the RSX-llM System Generation and Installation Guide ) . 
Features previously discussed that are not repeated in this section 
include : 

• Some device-specific QIC functions (see Section 2.3.2) 

• Special keys: CTRL/R — Write incomplete input buffer (see 

Section 2.5.1) 

CRT rubout (see Section 2.5.2) 

• Escape sequences (see Section 2.6) 

The only remaining features selected at SYSGEN time are 
terminal-independent cursor control (described in Section 2.15), 
private buffer pool size, and hard receive error detection, described 
in the following sections. 



2.9.1 Private Buffer Pool Size 

The private buffer pool is contained within the full-duplex terminal 
driver. The size of the whole driver is established during SYSGEN by 
the VMR command to load the driver as follows: 

LOA TT:/SIZE=nnn 

The private buffer pool occupies all of the space from the top of the 
actual driver code up to nnn. The argument nnn is expressed in octal 
words, and the maximum value is 20000, corresponding to 8K words. 
Depending on driver options selected, the code requires from 2.5 to 
4.5k words. Thus, the maximum buffer pool size is from 3.5k to 5.5k 
words. 

Alternatively, on an RSX-llM-PLUS system, it is possible to allocate 
tne private pooi m a separate uumunjn Dj-Oi^ri >_aj.j.ea ii^v^.-i. ^n^s ^^t^^., 
can range in size up to 4k words. The default size is 4k words, but 
it is modifiable, using the SIZE keyword with the VMR LOA command. In 
this case, the private pool is used almost exclusively for data 
buffers. Other driver-specifc data is allocated from secondary pool. 
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2.9.2 Hard Receive Error Detection 

All terminal interfaces supported by the full-duplex terminal driver 
are capable of detecting and flagging hard receive errors. Hard 
receive errors include framing errors, enable character parity error, 
and data overrun error. 



NOTE 

The driver does not enable parity 
generation and checking on DHll and DZll 
interfaces. 



If the hard receive error detection SYSGEN option (T$$RED) is 
selected, the driver handles hard receive errors as follows: 

1. If a read request is being processed and the character can be 
processed immediately, the read request is terminated with 
one of the following error codes returned in the status 
block : 



Error 
Code 



Hard Receive Error 



lE.BCC 
lE.DAO 
lE.VER 



Framing error 
Data overrun 
Character parity error 



2. If a command line is being input for a command line 
interpreter task and the character can be processed 
immediately, a CTRL/U is simulated, "U is echoed, and the 
input is terminated. No command line is sent to the task. 

3. If the character would normally cause an AST if no error was 
detected, the character is ignored and no AST occurs. 

4. If the character cannot be processed immediately, it is 
stored in the type-ahead buffer. A flag is set for the line, 
indicating that the last character in the type-ahead buffer 
has an error, disabling further storage in the type-ahead 
buffer. When the character is retrieved from the buffer, the 
appropriate action previously described is taken and the flag 
is cleared. Any characters received in the meantime are 
discarded, with a bell echoed for each character. 

If the T$$RED option is not selected, hard receive errors are ignored. 



2.10 TASK BUFFERING OF RECEIVED CHARACTERS 

When task-buffering received characters, characters read from the 
terminal are sent directly to the task's buffer. Thus, there is no 
need to allocate a terminal driver buffer. 

Task buffering of received characters does not necessarily reduce 
system overhead. For example, in a mapped system each character must 
be mapped to the task's buffer. However, if terminal driver buffering 
was used, the mapping is only done once for all characters to be 
transferred. 
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With the full duplex terminal driver, output buffering is always 
performed. -' 

Task buffering is overridden during checkpointing. If a task is 
checkpointable, a driver buffer is allocated and the task is made 
eligible for checkpointing by any task, regardless of priority, while 
the read operation is in progress. (Checkpointing only occurs in this 
situation when there is another task that can be made active.) Since 
checkpointability is controlled by the task, the user retains control 
over this operation. 



2.11 TYPE-AHEAD BDFFERING 

Characters received by the terminal driver are either processed 

immediately or stored in the type-ahead buffer. The type-ahead buffer 

allows characters to be temporarily stored and retrieved FIFO. The 
type-ahead buffer is used as follows: 

1. Store in buffer: 

An input character is stored in the type-ahead buffer if one 
or more of the following conditions are true: 

• The driver is not ready to accept the character (fork 
process pending or in progress) . 

• There is at least one character presently in the 
type-ahead buffer. 

• The character input requires echo and the output line to 
the terminal is presently busy outputting a character. 

• No read request is in progress, no unsolicited input AST 
is specified, and the terminal is attached. 

NOTE 

Depending on the terminal mode and the presence of a 
read function, read subf unctions and an unsolicited 
input AST, the CTRL/C, CTRL/0, CTRL/Q, CTRL/S , and 
CTRL/X characters may be processed immediately and 
not stored in the type-ahead buffer. 

A character is not echoed when it is stored in the buffer. 
Echoing a character is deferred until it is retrieved from 
the buffer, since the read mode (for example, 
read-without-echo) is not known by the driver until then. 

2. Retrieve from buffer: 

When the driver becomes ready to process input, or when a task issues 
a read request, an attempt is made to retrieve a character from the 
buffer. If this attempt is successful, the character is processed and 
echoed, if required. The driver then loops, retrieving and processing 
characters until either the buffer is empty, the driver becomes unable 
to ^process another character, or a read request is finished with the 
i-eriiiinax attached. 
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3. Flash the buffer: 

The buffer is flushed (cleared) when: 

1. CTRL/C is received. 

2. CTRL/X is received. 

3. The terminal becomes detached. 

Exceptions: CTRL/C and CTRL/X do not flush the buffer if 
read-pass-all or read-with-special-terminators is in effect. 

If the buffer becomes full, each character that cannot be entered 
causes a BELL character to be echoed to the terminal. 

If a character is input and echo is required, but the transmitter 
section is busy with an output request, the input character is held in 
the type-ahead buffer until output (transmitter) completion occurs. 



2.12 FDLL-DDPLEX OPERATION 

When a terminal line is in the full-duplex mode, the full-duplex 
driver attempts to simultaneously service one read request and one 
write request. The Attach, Detach and Set Multiple Characteristics 
functions are only performed with the line in an idle state (not 
executing a read or a write request) . 



2.13 PRIVATE BUFFER POOL 

The driver has a private buffer pool for intermediate input and output 
buffers on both RSX-llM and RSX-llM-PLUS systems, and type-ahead 
buffers and UCB extensions on RSX-llM systems only. Whenever the 
driver needs dynamic memory, it first attempts to allocate a buffer in 
the private pool. If this fails, a second attempt is made in the 
system pool. If the allocation in the system pool fails during 
command line input, a CTRL/U is simulated and echoed. 

Command line interpreter task buffers are handled in a special way. 
When unsolicited input begins, a buffer is allocated, as previously 
described, for the command line (a string of characters, followed by 
an appropriate terminator character) . When the input is completed, 
the contents of the buffer is sent directly to the command line 
interpreter task if the buffer was allocated in the system pool. 
However, if the buffer was allocated in the driver's private pool, it 
must first be moved into a buffer in the system pool to provide access 
for the task. 



2.14 INTERMEDIATE INPUT AND ODTPOT BUFFERING 

Input buffering for checkpointable tasks with checkpointing enabled is 
provided in the private pool. As each buffer becomes full, a new 
buffer is automatically allocated and linked to the previous buffer. 
The Executive then transfers characters from these buffers to the task 
buffer and the terminal driver deallocates the buffers once the 
transfer has been completed. 
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If the driver fails to allocate the first input buffer, the characters 
are transferred directly into the task buffer. If the first buffer is 
successfully allocated, but a subsequent buffer allocation fails, the 
input request terminates with the error code IE. NOD. In this case, 
the I/O status block contains the number of characters actually 
transferred to the task buffer. The task may then update the buffer 
pointer and byte count and reissue a read request to receive the rest 
of the data. The type-ahead buffer ensures that no input data is 
lost. 

All terminal output is buffered. As many buffers as required are 
allocated by the terminal driver and linked to a list. If not enough 
buffers can be obtained for all output data, the transfer is done as a 
number of partial transfers, using available buffers for each partial 
transfer. This is transparent to the requesting task. If no buffers 
can be allocated, the request terminates with the error code IE. NOD. 

The unconditional output buffering serves three purposes: 

1. It reduces time spent at system state. 

2. It enables long DMA transfers for DHll controllers. 

3. It enables task checkpointing during the transfer to the 
terminal (if all output fits in one buffer list). 



2.15 TERMINAL- INDEPENDENT CORSOR CONTROL 

Terminal-independent cursor control capability is provided at SYSGEN 
time. The terminal driver responds to task I/O requests for cursor 
positioning without the task requiring information about the type of 
terminal in use. I/O functions associated with cursor positioning are 
described as follows. 

Cursor position is specified in the vfc parameter of the lO.WLB or 
10. RPR function. The parameter is interpreted simply as a vfc 
parameter if the high byte of the parameter is 0. However, if the 
parameter is used to define cursor position, the high byte must be 
nonzero, the low byte is interpreted as column number (x-coordinate) , 
and the high byte is interpreted as line number (y-coordinate) . Home 
position, the upper left corner of the display, is defined as 1,1. 
Depending upon terminal type, the driver outputs appropriate 
cursor-positioning commands appropriate for the terminal in use that 
will move the cursor to the specified position. If the most 
significant bit of the line number is set, the driver clears the 
display before positioning the cursor. 

When defining cursor position in an lO.WLB function, the TF.RCU 
subfunction can be used to save the current cursor position. When 
included in this manner, TF.RCU causes the driver to first save the 
current cursor position, then position the cursor and output the 
specified buffer, and, finally, restore the cursor to the original 
(saved) position once the output transfer has been completed. 



2.16 TERMINAL INTERFACES 

This section summarizes the characteristics of the standard • 
communication-line interfaces supported by RSX-llM. Refer to the 
Terminals and Communications Handbook for additional details. 
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2.16.1 DHll Asynchronoas Serial Line Multiplexer 

The DHll multiplexer interfaces up to 16 asynchronous serial 
communications lines for terminal use. The DHll supports programmable 
baud rates. Input and output baud rates may differ; the input rate 
may be set to baud, thus effectively turning off the terminal. The 
DMll-BB option may be included to provide modem control for dial-in 
lines. These lines must be interfaced by means of a full duplex modem 
(for example, in the United States, a Bell 103A or equivalent modem). 



2.16.2 DHVll Asynchronous Serial Line Multiplexer 

The DHVll multiplexer interfaces up to eight asynchronous serial 

communications lines for terminal use. This multiplexer is the Q BUS 

version of the DHll UNIBUS multiplexer. 

programmable baud rates with the option 

operation. (Split speed operation allows 

receive speeds.) Also provided is modem 

point-to-point operation. 



The DHVll supports 
of selecting split speed 
different transmit and 
control for full-duplex 



2.16.3 DJll Asynchronous Serial Line Multiplexer 

The DJll multiplexer interfaces as many as 16 asynchronous serial 
lines to the PDP-11 for local terminal communications. The DJll does 
not provide a dial-in capability. Baud rates are jumper selectable. 



2.16.4 DLll Asynchronous Serial Line Interface 

The DLll supports a single asynchronous serial line and handles 
communication between the PDP-11 and a terminal. A number of standard 
baud rates are available to DLll users. However, since the DLll does 
not have an input silo, baud rates greater than 1200 baud are not 
recommended. Higher baud rates may cause input characters to be lost. 



For hardware reasons, a DLll is susceptible to 
interrupt enable in its Receiver Status Register, 
the receiver interrupt bit causes the terminal 
requests but not to respond to input (for example, 
not echo input characters) . The terminal driver has 
recognizing the disabling. Therefore, it cannot 
must be reset with an MCR OPEN command, the console 
or a periodically rescheduled task. 



losing receiver 
The disabling of 
to print output 
the terminal does 
no mechanism for 
recover. The bit 
switch register. 



2.16.5 DZll Asynchronous Serial Line Multiplexer 

The DZll multiplexer interfaces up to eight asynchronous serial 
communication lines for use with terminals. It supports programmable 
baud rates; however, transmit and receive baud rates must be the 
same. The DZll can control a full duplex modem in auto-answer mode. 
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2.17 PROGRAMMING HINTS 

2.17.1 Escape Code Conversion 

If escape sequences are recognized, the character code 037 will 
terminate input and a status code IS. ESC is returned. In addition, 
character codes will terminate input and return the IS. ESC status if 
upper- to lowercase conversion is not enabled. 



2.17.2 RT02-C Control Function 

Because the screen of an RT02C Badge Reader and Data Entry Terminal 
holds only one line of information, special care must be taken when 
sending a control character (for example, vertical tab) to the RT02-C. 
Use the lO.WAL (Write All) function for this purpose. 

It is recommended that read without echoing be used when reading a 
badge with the RT02-C. Use lO.RAL or lO.RNE functions, followed by 
the lO.WAL function, to echo the information for display. 
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2.17,3 Using lO.WVB Instead of lO.WLB 

Using lO.WVB instead of lO.WLB is recommended when writing to a 
terminal. If the write actually goes to a terminal, the Executive 
converts the lO.WVB to an lO.WLB request. However, if the LUN has 
been redirected to an inappropriate device (for example, a disk) , the 
use of an lO.WVB function will be rejected because a file is not open 
on the LUN. This prevents privileged tasks from overwriting block 
zero of the disk. 

Note that any subfunction bits specified in the lO.WVB request (for 
example, TF.CCO, TF.WAL, or TF.WBT) are stripped when the lO.WVB is 
converted to an lO.WLB. 



2.17.4 Remote DLll-E, DHll, and DZll Lines 

Before a remote line is answered, the driver clears certain terminal 
characteristics (see Table 2-5) that may have been set by an MCR SET 
command, or by an SF.SMC function. The characteristics cleared are: 
TC-SCP, TC.BSQ, TCJitTD, TC.SMR, TC.,»8rC, TC.J!©X, TCJiFF, TC.HffT, 
TC.^L, TC.,[MT, TC^-^TP, TC,-&e'C, and TCUS^KT. (Clearing TC.TTP means 
that a terminal type of "unknown" will be returned in an SF.GMC 
request.) The TC.ACR characteristic (automatic wrap around) is set. 
Buffer si2e is set to 72. 

A DZll remote line must be declared to be remote before the terminal 
driver will handle the modem. 



2.17.5 Side Effects of Setting Characteristics 

Certain terminal characteristics that a task may set or that an 
operator may set using MCR commands may have undesirable side effects. 
In particular, these characteristics include the hold-screen mode and 
the lower- to uppercase conversion disable mode. Their effects are 
described as follows. 

TC.HLD — Unexpected behavior can result from a terminal in the 
hold-screen mode if its reception rate is much greater than its 
transmission rate. (The DHll supports split baud rates.) When in the 
hold-screen mode, the terminal automatically sends a CTRL/S during 
reception of an output stream when the screen is nearly full. Output 
is resumed — another screen-full — when you type SHIFT/SCROLL (the 
terminal generates CTRL/Q) . Thus, no output is lost as a result of 
scrolling off the screen before you can read it. However, if the 
terminal's transmission rate is far below its reception rate, some 
unread output may scroll out of sight before the CTRL/S can be 
transmitted. 

Note that some terminals and interfaces are hardware buffered. This 
can cause obscure timing problems for tasks that attempt to invoke the 
hold-screen mode. 

TC.SMR — If this characteristic is asserted (lower- to uppercase 
conversion is disabled) , octal characters 175 and 176 are interpreted 
as "right brace (. \ ) " and "tilde {~)," respectively. If TC.SMR is 
not asserted, these characters are interpreted as an Altmode (that is, 
they function as line terminators that do not advance the cursor to a 
new line) . 
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2.17.6 Modem Support 

The terminal driver supports the following modem control operations: 

• Local or remote operation 

• Answer speed 

• Auto-baud speed detection 

The characteristics bit that controls local or remote operation is 
TC.DLU. This bit can be set with the MCR command SET /REMOTE (or SET 
/NOREMOTE for local operation) . The DCL command SET TERMINAL REMOTE 
(or SET TERMINAL LOCAL) can also be used. 

When there is an incoming call on a remote line, the TC.ASP 
characteristic determines the baud rate for the answering modem. 



Split baud rates (different 
supported for answer speed. 



transmit and receive speeds) are not 



The default answer speed is set at SYSGEN time. However, the answer 
speed can be set on line using the MCR command SET /REMOTE=TTnn : speed . 
VMR can also be used to set the answer speed. 

The terminal driver can determine the speed of the incoming call by 
sampling the first input character after dial-up for the following 
speeds: 

110 
150 
300 
1200 

This is called auto-baud speed detection. This option can be selected 
for each line using the SET /ABAUD command. This command sets the 
TC.ABD terminal characteristic. When TC.ABD is set for a given line, 
the terminal driver makes three attempts to determine the incoming 
speed. If the auto-baud speed detection fails, the terminal driver 
will use the default answer speed discussed above. 

For auto-baud speed detection to work correctly, the first input 
character after dial-up must be either carriage return or CTRL/C. 



2-42 



CHAPTER 3 
HALF-DUPLEX TERMINAL DRIVER 



3.1 INTRODUCTION 

The half-duplex terminal driver provides support for a variety of 
terminal devices under RSX-llM. (This terminal driver is not 
supported on RSX-llM-PLUS systems.) The half-duplex terminal driver is 
generally used in RSX-llM systems where small driver size is 
essential, and the additional functional capability provided by the 
larger full-duplex terminal driver (described in Chapter 2) is not 
required. Table 3-1 summarizes the terminals supported, and 
subsequent sections describe these devices in greater detail. 

Table 3-1 
Supported Terminal Devices 



Model 



Columns 



ASR-33/35 


72 


KSR-33/35 


72 


LA12 


132 


LAI 00 


132 


LA30-P 


80 


LA30-S 


80 


LA34 


132 


LA36 


80-132 


LA38 


132 


LAI 2 


132 


LA180S 


132 


RT02 


64 


RT02-C 


64 


VT05B 


72 


VT50 


80 


VT50H 


80 


VT52 


80 


VT55 


80 


VT61 


80 


VTIOO 


80-132 


VTlOl 


80-132 


VT102 


80-132 


VT10 5 


80-132 


VT125 


80-132 


VT131 


80-132 


VT132 


80-132 



Lines/ 
Screen! 



Characte: 
Set 



1 

1 

20 

12 

12 

24 

24 

24 

24 

24 

24 

24 

24 

24 

24 



64 
64 
96 
96 
64 
64 
96 
64-96 
96 
96 
96 
64 
64 
64 
64 
54 
96 
96 
96 
96 
96 
96 
96 
96 
96 
96 



1. Applies only to video terminals. 

2. Only for 96-character terminal, 
the terminal interfaces summarized 
are described in greater detail in 
identical for all. 



Baud 
Range 



110 
110 
50-9600 
110-9600 

300 
110-300 
110-300 
110-300 
110-300 

50-9600 

300-9600 

110-1200 

110-1200 

110-2400 

110-9600 

110-9600 

110-9600 

110-9600 

110-9600 

50-9600 

50-19200 

50-9600 

50-9200 

50-9600 

50-19200 

50-19200 



Upper- & Lowercase? 



Send 



Receive 



yes 
yes 



yes 
yes 
yes 
yes 



yes 



yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 



yes 
yes 



yes 
yes 2 

yes 
yes 
yes 



yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 
yes 



The terminal 
in Table 3-2. 
Section 3.9. 



driver supports 

These interfaces 

Programming is 
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Table 3-2 
Standard Terminal Interfaces 



Model 



DHll 

DHll-DMll-BB 

DJll 

DLll-A/B/C/D/W 

DLVll-F 

DZll 



Type 



16-line multiplexer-^ 

16-line multiplexer with modem control'^ 

16-line multiplexer 

Single-line interfaces 

Single-line interface 

8-line multiplexer with modem control^ 



1. Direct memory access (DMA) not supported. 

2. Full-duplex control only. For example, in the USA, a 
Bell 103A-type modem. 

Terminal input lines can have a maximum length of 255 bytes (the 

maximum is set in the system generation, or SYSGEN, dialog). The 

extra characters of an input line that exceeds the maximum length 
generally become an unsolicited input line. 



3.1.1 ASR-33/35 Teletypes-^ 

The ASR-33 and ASR-35 Teletypes are asynchronous, hard-copy terminals. 
No paper tape reader or punch capability is supported. 



3.1.2 KSR-33/35 Teletypes 1 

The KSR-33 and KSR-35 Teletypes are asynchronous, hard-copy terminals. 

3.1.3 LA30 DECwriters 

The LA30 DECwriter is an asynchronous, hard-copy terminal that^ is 
capable of producing an original and one copy. The LA30-P is a 
parallel model and the LA30-S is a serial model. 



3.1.4 LA36 DECwriter 

The LA36 DECwriter is an asynchronous terminal that produces hard copy 
and operates in serial mode. It has an impact printer capable of 
generating multipart and special preprinted forms, 
receive and transmit both uppercase and lowercase characters, 



The LA36 can 



1. Teletype is a registered trademark of the Teletype Corporation, 
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3.1.5 LA120 DECwriter 

The LA120 DECwriter is a hard-copy, upper- and lowercase terminal 
capable of printing multipart forms at speeds up to 180 
characters-per-second. Serial communications speed is selected from 
14 baud rates ranging from 50 to 9600 bps. Hardware features allow 
bidirectional printing for maximum printing speed, and also allow 
user-selected features, including font size, line spacing, tabs, 
margins, and forms control. These functions can also be set up by 
user tasks that issue appropriate ANSI-standard escape sequences. 



3.1.6 LA180S DECprinter 

The LA180S DECprinter is a serial version of the LA180. It is a 
print-only device (it has no keyboard) that can generate multipart 
forms. The LA180S can print uppercase and lowercase letters. 



3.1.7 RT02 Alphanumeric Display Terminal and RT02-C Badge Reader/ 
Alphanumeric Display Terminal 

The RT02 is a compact, alphanumeric display terminal designed for 
applications in which source data is primarily numeric. A shift key 
permits the entry of 30 discrete characters, including uppercase 
alphabetic characters. The RT02 can, however, receive and display 64 
characters. 

The RT02-C model also contains a badge reader. This option provides a 
reliable method of identifying and controlling access to the PDP-11 or 
to a secure facility. Furthermore, data in a format corresponding to 
that of a badge (22-column fixed data) can be entered quickly. 



3.1.8 VT05B Alphanumeric Display Terminal 

The VT05B is an alphanumeric display terminal that consists of a CRT 
display and a self-contained keyboard. From a programming point of 
view, it is equivalent to other terminals, except that the VT05B 
offers direct cursor addressing. 



3.1.9 VT50 Alphanumeric Display Terminal 

The VT50 is an alphanumeric display terminal that consists of a CRT 
display and a keyboard- It is similar to the VT05B in operation, but 
does not offer direct cursor addressing. 



3.1.10 VT50H Alphanumeric Display Terminal 

The VT50H is an alphanumeric display terminal with CRT_ display, 
keyboard, and numeric pad. It offers direct cursor addressing . (The 
VTSOH's direct cursor addressing is not compatible with that of the 
VT05B.) 
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3.1.11 VT52 Alphanumeric Display Terminal 



The VT52 is an upper- and lowercase alphanumeric terminal with numeric 

pad and direct cursor addressing. (The VT52's direct cursor 

addressing is comi 

the 

printer, 



and direct cursor addressing. (The VT52's direct cursor 

3ssing is compatible with that of the VT50H, but not with that of 

VT05B.) The VT52 can be configured with a built-in thermal 

hay 



3.1.12 VT55 Graphics Display Terminal 

The VT55 is similar to the VT52 in its operation as an alphanumeric 
terminal. The VT55 offers graphics display features that are not 
supported by RSX-llM, although the system allows a knowledgeable task 
to access the explicitly special features of the VT55. 



3.1.13 VT61 Alphanumeric Display Terminal 

The VT61 is an "intelligent" upper- and lowercase alphanumeric 
terminal with an integral microprocessor. It offers two 128-member 
character sets and numerous built-in functions for editing and 
preparing forms, as well as a block-transfer mode. (None of these 
special features is supported by RSX-llM.) 



3.1.14 VTIOO DECscope 

The VTIOO DECscope is an upper- and lowercase alphanumeric 
keyboard/video display terminal. It is capable of displaying 24 lines 
of 80 characters (each line) . Serial communications speed is selected 
from baud rates ranging from 50 to 9600 bps. Hardware features allow 
user selection of display characteristics and functions including 
smooth scroll, reverse video, and so forth. These functions can also 
be set up by user tasks that issue appropriate ANSI-standard escape 
sequences . 



3.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for terminals. A setting of 1 indicates that the 
described characteristic is true for terminals. 

Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File structured device 

Single-directory device 

Sequential device 

Mass storage device 
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Bit 


Setting 





1 


1 


1 


2 


1 


3 





4 





5 





6 
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Bit 


Setting 


7 





8 





9 





10 





11 





12 





13 





14 





15 






Meaning 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications 
channel 

Device mountable as a FILES-11 volume 

Device mountable 



Words 3 and 4 are undefined. Word 5 indicates the default buffer 
size for the device: for terminals the width of the terminal carriage 
or display screen. 



3.3 QIO MACRO 

Table 3-3 lists the standard and device-specific functions of the QIO 
macro that are valid for terminals. All device-specific functions are 
options that may be selected at system generation. 

Two device-specific functions, SF.SMC and SF.GMC, have nonstandard 
function names. These names are designed for compatibility with IAS. 



Table 3-3 
Standard and Device-Specific QIO Functions for Terminals 



Format 


Function 


STANDARD FUNCTIONS: 

QIO$C 10. ATT, . .. 

QI0$C lO.DET,. .. 

QIOSC lO.KIL,... 

QIO$C lO.RLB,. . .,<stadd,size> 

QIOSC lO.RVB,. . . ,<stadd,size> 

QIO$C lO.WLB,. . . ,<stadd,size,vfc> 

QIO$C lO.WVB, . . . ,<stadd ,size,vfc> 


Attach device 

Detach device 

Cancel I/O requests 

READ logical block 

(read typed input into buffer) 

READ virtual block 

(read typed input into buffer) 

WRITE logical block 
(print buffer contents) 

WRITE virtual block 
(print buffer contents) . 



(continued on next page) 
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Table 3-3 (Cont.) 
Standard and Device-Specific QIO Functions for Terminals 



Format 



Function 



DEVICE-SPECIFIC FUNCTIONS 
(ALL SYSGEN OPTIONS) : 

QIO$C lO.ATA, .. . ,<ast> 



QIO$C lO.CCO, . . . ,<stadd ,size,vfc> 

QIO$C SF.GMC, ,<stadd,size> 

QIO$C lO.GTS, . . . ,<stadd,size> 
QIO$C lO.RAL, . . . ,<stadd,size> 

QIO$C lO.RNE, , . . ,<stadd ,size> 

QIO$C lO.RPR, . . . ,<stadd,size, 
[tmo] ,pradd,prsize,vfc> 

QIO$C lO.RST, . . . ,<stadd ,size> 

QIO$C SF.SMC, ,<stadd,size> 

QIO$C lO.WAL, . . . ,<stadd,size> 

QIO$C lO.WBT, . . . ,<stadd ,size,vfc> 



ATTACH device, specify 
unsolicited- input-character 
AST 

CANCEL CTRL/O (if in effect), 
then write logical block 

GET multiple characteristics 

GET terminal support 

READ logical block, pass all 
bits 

READ logical block, do not echo 

READ logical block after prompt 



READ logical block ended by 
special terminators 

SET multiple characteristics 

WRITE logical block, pass all 
bits 

WRITE logical block, break 
through most I/O conditions at 
terminal 



ast 



The entry point for an unsolicited-input-character AST. 



pradd 



The starting address of the byte buffer where the prompt is 
stored. The buffer must be within the task's address space. 



prsize 



The size of the pradd prompt buffer in bytes. If the system 
supports variable length reads, the buffer size must be greater 
than and less than or equal to 255. If the system does not 
support variable length reads, the specified size must be greater 
than and less than or equal to 80, 
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Size 



The size of the stadddata buffer in bytes (must be greater than 
• u. . . function is a read and the system supports 
variable-length reads, the size must be less than or equal to 
255. Otherwise, the size must be less than or equal to 80. The 
buffer must be within the task's address space. For SF GMC 
InkV'^f', !"^, SF.SMC, the size must be an even number less'than 
4065 (decimal). If the function is a write, size can be up to 
JzK bytes. 



stadd 



The starting address of the data buffer. The address must be 
word aligned for SF.GMC, 10. GTS, and SF.SMC; otherwise, stadd 



ma 



y be on a byte boundary. 



tmo 



vfc 



An optional time-out count, included for IAS compatibility. If 
supplied, it is ignored. ^^^y. 



A character for vertical format control from Table 3-11 (see 



3.3.1 Subfunction Bits 

Most of the device-specific functions supported by the terminal driver 
are implemented by way of "subfunction bits." That is, these functions 
can be invoked by ORing a named bit with some other function. Table 
3-4 shows the relationship of the 10 subfunction bits to the standard 
and device-specific functions. 

The 10 subfunction bits, and their octal values, are: 



TF.AST Unsolicited-input-character AST 10 
TF.BIN Binary prompt 2 

40 
20 
10 
20 



TF.CCO Cancel CTRL/0 

TF.ESQ Recognize escape sequences 

TF.RAL Read all bits 

TF.RNE Read with no echo 

31^-RST Read with special terminators "1 

10 
100 
100 



TF.WAL Write all bits 
TF.WBT Break-through write 
TF.XOF Send XOFF 



The subfunction bits are defined in the system module TTSYM (discussed 
further in Section 3.3.2.5). The octal values of these entitles are 
th^^^^w to change; therefore, it is recommended that you aliays use 

l.n h!^np°y'-2r'f- .""^ ^'^^" ^-^ ^'^°^^' 7 °f the 10 subfunction b??I 
can be ORed with standard QIO functions to invoke device-specific 
functions. The remainina three subfnnnHr^r, k,-4-o ,tt? nrx, mp „^„ _ , 
TF XOF) can be ORed with Attachand Re'adXf ter^^om^t 'qiS^ to ;rovide 
added features, as described in Section 3.3.2. 
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Of the 10 subfunction bits, 3 can be used with Read QIO functions, 3 
with Write functions, 2 with Attach functions, and 5 with Read After 
Prompt. The breakdown is: 

Read TF.RAL, TF.RNE, TF.RST 

Write TF.CCO, TF.WAL, TF.WBT 

Attach TF.AST, TF.ESQ 

Read After Prompt TF.BIN, TF.XOF, TF.RAL, TF.RNE, TF.RST 

If a task invokes a subfunction bit that is not supported on the 
system, the subfunction bit is ignored "^^'^^^^ected For example, if 
Read with special Terminators is not selected, either lO.RST or 
lO.RLBITF.RST is interpreted as lO.RLB. 

The following example shows a QIO request using more than one 
subfunction bit: a nonechoed read, which may be concluded by a 
special terminator, after a prompt. 

QIO$C lO.RPRlTF.RNElTF.RST,. . . ,<stadd , si ze , ,pradd ,prsize , vf c> 



3.3.2 Details on Device-Specific QIO Functions 

All the device-specific functions described in this section are SYSGEN 
options ill except SF.GMC, 10. RPR, SF.SMC, and lO.GTS can be issued 
bf iS?ng a particular subfunction bit with another QIO function 
These LbfEnction bits are specified in the text; subfunction bits 
are described in general in Section 3.3.1. 

in addition to the 11 device-specific QIO functions, this section also 
g?ves details on the features provided by the 3 subfunction bits 
TF.ESQ, TF.BIN, and TF.XOF. 



3 3 2 1 10. ATA - 10. ATA is a variation of the Attach directive. It 
s^e^ifies ;n asynchronous system trap (AST) to process an unsolicited 
input character. When called as follows: 

QI0$C lO.ATA,. ..,<ast> 

this function attaches the terminal and identifies "ast" as the entry 
Joint for an unsolicited-input-character AST Control passes to this 
address whenever any unsolicited character (other than CTRL/Q, CTRL/S, 
or CTRL/0) is input. Note that little checking is done on the 
specmc AST address. A bad address is frequently detected only when 
the Executive tJLs to transfer control to it and the task crashes. 

Tn particular, CTRL/C is trapped by the task and does not reach MCR. 
Sus any t^sk that uses lO.ATA should recognize _ some- input sequence 
Is a request to terminate, because MCR can not be invoked to abort the 
task in case of difficulty. 

Note that this mechanism is intended to get a single character into 
the system - not a series of characters. Since the driver must 
becom^'a fSrk process in order to declare an AST a ^ nd cha ac r 
can arrive before the driver can queue an AST for the first character. 
The buffer for unsolicited input characters, however, is one byte 
lonq Therefore, the terminal driver ignores the second character. 
SrcircumsJance'can occur because of fast input on a busy system or 
because output is in progress when the characters are received The 
implications of this are that neither type-ahead nor full duplex 
iperaUons can be simulated perfectly using unsolicited character 
ASTs. 
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Table 3-4 
Subfunction Bits 



I 

^3 



Function 


Equivalent with 
subfunction bits 




Allowed Subfunction 


Bits 








TF.AST 


TF.BIN 


TF.CCO 


TF.ESQ 


TF.RAL 


TF.RNE 


TF.RST 


TF.WAL 


TF.WBT 


TF.XOF 


STANDARD FUNCTIONS 


X 






X 














10. ATT 




lO.DET 
























lO.KIL 
























lO.RLB 












1 


X 


1 








lO.RVB 












2 


2 


2 








lO.WLB 








X 










X 


X 




lO.WVB 








2 


X 








2 


2 




DEVICE-SPECIFIC FUNCTIONS 


10. ATA 


lO.ATTITF.AST 


lO.CCO 


lO.WLBlTF.CCO 
















X 


X 




SF.GMC 
























10. GTS 
























lO.RAL 


lO.RLBJTF.RAL 












X 


1 








lO.RNE 


lO.RLBSTF.RNE 










1 




1 








10. RPR 






X 






1 


X 


1 






X 


lO.RST 


lO.RLBITF.RST 










1 


X 










SF.SMC 
























lO.WAL 


lO.WLBiTF.WAL 






X 












X 




lO.WBT 


lO.WLBlTF.WBT 






X 










X 







as 

> 

I 
O 

G 

r 

M 
X 

n 

3 

M 

a 
> 

o 

M 
< 

M 
W 



Jesult"'^'^^ ^"^^^ "^'^^ "^^" "^^"^ ''^"^ ^"^^ ^""^ "^^""^ "^"^^ Special Terminators together. Obscure problems can 



2. These subfunction bits are allowed but are not effective. They are stripped off when the read 
virtual is converted to a read or write logical. 



or write 
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At entry, the unsolicited character is the low-order byte of the top 
word on the stack. Before exiting the AST, be sure to pop that word 
off the stack; otherwise, the task will crash. In all other respects 
the AST environment is standard: 

SP+10 Event flag mask word 

SP+06 PS of task prior to AST 

SP+04 PC of task prior to AST 

SP+02 Task's directive status word 

SP+00 Unsolicited character in low byte 

See the RSX-llM/M-PLUS Executive Reference Manual for further details 

on ASTs: Sii — siFtion 3.10.10 for hints on ASTs in a multiterminal 

environment. 

10. ATA is equivalent to 10. ATT ORed with the subfunction bit TF.AST. 



3 3 2 2 10 ATT' TF. ESQ - The task issuing this directive attaches a 
terminal and notifies the driver that it recognizes escape sequences 
input from that terminal. Escape sequences are recognized only for 
solicited input. See Section 3.6 for a discussion of escape 
sequences. 




Se'terStnaractras^rfine'terminator. The SF. SMC QIO or the MCR SET 
/ESCSEQ command is used to declare the terminal capable of generating 
escape sequences (see Table 3-5 and Section 3.3.2.12). 



3 3 2 3 10 ceo - This write function directs the driver to write to 
the' terminal regardless of a CTRL/O condition that may be m effect. 
If CTRL/O is in effect, it is canceled before the write is done. 

10. ceo is equivalent to lO.WLB'TF.CCO. 



3 3 2 4 SF.GMC - The Get Multiple Characteristics function returns 
information on terminal characteristics. Get Multiple Characteristics 
is used in the following way: 

QIO$C SF.GMC,.. . ,<stadd,size> 



stadd 



The starting address of a data buffer of length "size" bytes, 
Each word in the buffer has the form 



.BYTE characteristic-name 
.BYTE 



characteristic-name 

One of the eight bit names given in Table 3-5. 
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The QIO function returns a value in the high-order byte of each 
byte-pair: 1 if the characteristic is true for the terminal, if not 
true. 



For the TC.TTP characteristic (terminal type), one of three values 
returned in the high-order byte, as shown in Table 3-6. 



IS 



NOTE 

The half-duplex terminal driver treats 
the terminal type as a required 
characteristic for the type of terminal 
specified. The terminal type (TC.TTP) 
does not set any implicit terminal 
characteristics other than those noted 
in Table 3-6. 



Table 3-5 
Terminal Characteristics for SF.GMC and SF.SMC Requests 



Bit 


Octal 


Meaning 


Corresponding 


Name 


Value 


(If Asserted): Terminal ... 


MCR Command 


TC.ASP3 


76 


Remote line answer speed 


SET /REMOTE=TI: speed 


TC.ESQ 

tc.hldI 


35 


...can generate escape sequences 


SET /ESCSEQ=TI: 


44 


...is in hold-screen mode 


SET /HOLD=TI: 


TC.NEC 
TC.PRl2 


47 


...is in no-echo mode 


SET /NOECHO=TI: 


51 


. . .is privileged 


SET /PRIV=TTnn: 


TC.SCP 


12 


. . .is a scope (CRT) 


SET /CRT=TI: 


TC.SLV 


50 


. . .is slaved 


SET /SLAVE=TTnn: 


TC.SMR 


25 


Uppercase conversion disabled 
on input 


SET /LOWER=TI: 


TC.TTP 


10 


Terminal type 


SET /LA30S=TI: 
SET /VT05B=TI: 


TC.HFF 

TC.RSP3 

TC.XSp3 


17 


...handle hardware form feeds 


SET /FORMFEED=TI: 


3 


Receiver speed 


SET /SPEED=TI:rcv:xmit 


4 


Transmitter speed 


(As above) 



1. Effective for VT5x and VT61 only. 

2. Cannot be changed by a task; must use MCR command, 

3. Recognized only by the SF.SMC function. 



Table 3-6 
Bit TC.TTP (Terminal Type): Values Set by SF.SMC 
and Returned by SF.GMC 



Octal Value 



Symbolic 



T.UNKO 
T.AS33 

T.L30S 

T.VT05 



Meaning 



Terminal type is unknown 

(resets all other types) 

Terminal is an ASR 

(sets uppercase conversion on 

output) 

Terminal is an LA30 

(sets horizontal fill after 

carriage return) 

Terminal is a VT05B 

(sets a vertical fill count of 4) 
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3.3.2.5 10. GTS - The Get Terminal Support QIO returns a 4-word buffer 
of information specifying which SYSGEN-option features are part of the 
terminal driver. Of these four words, two are currently defined. 
Table 3-7 gives details on these two words. The 10. GTS QIO is itself 
a SYSGEN option. If 10. GTS is issued on a minimum system (one with no 
terminal-driver SYSGEN options), lE.IFC is returned in the I/O status 
block. 



Table 3-7 
Information Returned by Get Terminal Support (10. GTS) QIO 



Bit 



Value 



Mnemonic 



Word of Buffer: 





1 

2 

3 

4 

5 

6 

7 

8 

9 

10 

11 

12 

13 

14 

15 



1 

2 

4 

10 

20 

40 

100 

200 

400 

1000 

2000 

4000 

10000 

20000 

40000 

100000 



Fl.ACR 
Fl.BTW 
Fl.BUF 
Fl.UIA 
Fl.CCO 
Fl.ESQ 
Fl.HLD 
Fl.LWC 
Fl.RNE 
Fl.RPR 
Fl.RST 
Fl.RUB 
Fl.SYN 
Fl.TRW 
Fl.UTB 

Fl.VBF 



Word 1 of Buffer: 



F2.SCH 
F2.GCH 



Meaning When Set to 1 



Automatic CR/LF on long lines 

Break-through write 

Checkpointing during terminal input 

Unsolicited-input-character AST 

Cancel CTRL/0 before writing 

Recognize escape sequences in solicited input 

Hold-screen mode 

Lower- to uppercase conversion 

Read with no echo 

Read after prompting 

Read with special terminators 

CRT rubout 

CTRL/R terminal synchronization 

Read all and write all 

Input characters buffered in task's address 

space 

Variable-length terminal buffers 



Set characteristics QIO (SF.SMC) 
Get characteristics QIO (SF.GMC) 



The various symbols used by the 10. GTS, SF.GMC, and SF.SMC QIOs are 
defined in a system module, TTSYM. These symbols include: Fl.xxx an^ 
F2.XXX (Table 3-7); T.xxxx (Table 3-6); TC.xxx (Table 3-5); and the 
SE.xxx error returns described in Table 3-8, Section 3.4. These 
symbols may be defined locally within a code module by using: 

.MCALL TTSYM$ 



TTSYM$ 

If the symbols are not defined locally, they are automatically defined 
by the Task Builder. 

The octal values of these symbols are subject to change. Therefore, 
it is recommended that you always use the symbolic names. 
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3.3.2.6 lO.RAL - The Read All function causes the driver to pass all 
bits to the requesting task. The driver does not intercept control 
characters or mask out the "parity" (high-order) bit. This means, for 
example, that CTRL/C, CTRL/Q, CTRL/S, CTRL/0, and CTRL/Z are passed to 
the program and are not interpreted by the driver. 

NOTE 

lO.RAL echoes the characters that are 
read. To read all bits without echoing, 
use lO.RALlTF.RNE. 

lO.RAL is equivalent to lO.RLB ORed with the subfunction bit TF.RAL. 
The only way to terminate an lO.RAL function is by a character count 
(that is, filling the input buffer) . 



3.3.2.7 lO.RNE - lO.RNE causes the driver to read a line from the 
terminal without echoing the characters that are input. This feature 
is useful when typing sensitive information: for example, a password 
or combination. lO.RNE is also used to read a badge with the RT02-C. 

(Another way to suppress echoing of input is to set the terminal to 
no-echo mode with the SF.SMC QIO or the MCR SET /NOECHO command. See 
Table 3-5, bit TC.NEC.) 

Note that the TC.NEC subfunction only suppresses echoing of solicited 
input. Unsolicited input is still echoed. 

CTRL/R, if selected as a SYSGEN option, is ignored while an lO.RNE is 
in progress. 

lO.RNE is equivalent to lO.RLB ORed with the subfunction bit TF.RNE. 



3.3.2.8 10. RPR - The QIO function 10. RPR (Read After Prompt) has the 
same effect as lO.WLB (to write a prompt to the terminal) followed by 
10. RLE. However, 10. RPR differs in four ways from this combination of 
QIOs. With 10. RPR: 

• System overhead is lower because only one QIO is processed. 

• There is no "window" during which a response to the prompt may 
be ignored. Such a window occurs if lO.WAL/IO.RLB is used, 
because no read may be posted at the time the response is 
received . 

• If the issuing task is checkpointable, it is checkpointed 
during both the prompt and the read. 

• A CTRL/0 that may be in effect is canceled before the prompt 
is written. 

The third user-specified argument to 10. RPR, tmo, is required for 
compatibility with IAS. If supplied, it is ignored. 

Subfunction bits may be ORed with 10. RPR to write the prompt as a 

Write All (TF.BIN) and to send XOFF after the read (TF.XOF) . See the 

next two sections. In addition, the three Read subfunction bits 
(TF.RAL, TF.RNE, TF.RST) can be used with 10. RPR. 
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3.3.2.9 I0.RPR1TF.BIN - This QIO function results in a read after a 
"binary" prompt, that is, a prompt that is written by the driver with 
no character interpretation (as if it were issued as an lO.WAL) . 



3.3.2.10 lO.RPR'TF.XOF - This QIO function causes the driver to send 
an XOFF to the terminal after its prompt-and-read. The XOFF, or 
CTRL/S, may have the effect of inhibiting input from the terminal, if 
the terminal recognizes XOFF for this purpose. 



3.3.2.11 lO.RST - This QIO function acts like lO.RLB, except that 
certain special characters terminate the read. These characters are 
in the ranges 0-37(8) and 175-177(8). The driver does not interpret 
the terminating character, with certain exceptions.! For example, a 
horizontal TAB (11 octal) is not expanded, a RUBOUT (or DEL, 177 
octal) does not erase, and a CTRL/C does not get MCR's attention. 

Upon successful completion of an lO.RST request that was not 
terminated by filling the input buffer, the I/O status block looks 
like the following: 

Terminating 
character 



lOSB 



IS.SUC&377 



# of bytes in buffer 



The terminating character is not in the buffer. 
lO.RST is equivalent to lO.RLBlTF.RST. 



3.3.2.12 SF.SMC - This QIO function allows a task to set and reset 
the characteristics of a terminal. Set Multiple Characteristics is 
the inverse of SF.GMC. Like SF.GMjC, it is called in the following 
way: 

QIOSC SF.SMC, ... ,<stadd,size> 

I 

The starting address of a buffer of length "size" bytes. 

Each word in the buffer has the form 

.BYTE characteristic-name 
.BYTE value 



stadd 



1. If upper- and lowercase conversion is disabled (see remarks in 
Section 3.10.9), the character 175(8) echoes as right-brace and 176(8) 
as tilde, and these characters do not act as terminators. The three 
characters CTRL/O, CTRL/Q, and CTRL/S (17, 21, and 23(8), 
respectively) are not special terminators. The driver interprets them 
as output effectors. 
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characteristic-name 

One of the symbolic bit names given in Table 3-5. 

value 

Either (to clear a given characteristic) or 1 (to set a 
characteristic) . Table 3-5 notes the restrictions that apply to 
these characteristics. 

If characteristic-name is TC.TTP (terminal type) , then value can have 
any of the values listed in Table 3-6. 

A nonprivileged task can only issue an SF.SMC request to affect its 
own terminal, TIO:. A privileged task can issue SF.SMC to any 
terminal . 



3.3.2.13 lO.WAL - The Write All function causes the driver to pass 
all output from the buffer without interpretation. It does not 
intercept control characters. Lines are neither wrapped around (if 
input/output wrap-around has been selected) nor truncated (if 
wrap-around is not selected) . 

lO.WAL is equivalent to lO.WLBlTF.WAL. 



3.3.2.14 lO.WBT - The Write Break Through function instructs the 
driver to write the buffer regardless of the I/O status of the 
receiving terminal. If an 10. WET is issued on a system that does not 
support 10. WET, it is treated as an lO.WLB. 

• If another write is in progress, it finishes and the lO.WBT is 
the next write issued. The effect of this is that lO.WBTs can 
be stopped by a CTRL/S. Therefore, tasks may still want to 
time out on 10. WET. 

• If a read is posted, the lO.WBT proceeds anyway, and an 
automatic CTRL/R is performed to redisplay any input that was 
received before the break-through write. 

• CTRL/S and/or CTRL/0, if in effect, are canceled. 

• Characters input during a break-through write are ignored. 

An lO.WBT cannot break through another 10. WET that is in progress or 
if a prompt is being- written by 10. RPR. In either case, the low-order 
byte of the first word of the I/O status block contains IE.RSU&377. 
The task receiving this error need only reissue the write. 

Break-through write may only be issued by a privileged task. However, 
the task does not have to be mapped to the Executive (Task Builder 
options /PR:4 or /PR:5). A task can use lO.WBT if it is built with 
the /PR:0 switch specified. The privileged MCR command ERO 
(broadcast) uses 10. WET. 

Break-through write cannot break through a multiecho. Instead, it 
returns error code lE.RSU. When this occurs, the task should reissue 
the write request. 
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3.4 STATUS RETURNS 

Table 3-8 lists error and status conditions that are returned by the 
terminal driver. 

Upon successful completion of a read, the I/O status block contains 
data of this sort: 



Byte 









Word 








1 


ret 


= 





means 


ret 


= 


15 


means 


ret 


= 


33 


means 


ret 


= 


233 


means 


+1 






is 



ret 


+1 


Number of bytes read 



read terminated by buffer full 
(byte count satisfied) ; 

IS.CR: read terminated by carriage return. 

IS. ESC: read terminated by an Altmode. 

IS. ESQ: read terminated by an escape sequence, 

IS.SUC: the return code for successful 
completion. 



Most RSX-llM return codes are byte values: for example, IS.SUC = 1 is 
a byte value. By contrast, the three return codes IS.CR, IS. ESC, and 
IS, ESQ are word values. The low-order byte indicates successful 
completion, and the high-order byte is required to show what type of 
completion occurred. 

To test for one of these word-value "return codes, first test the 
low-order byte of the first word of the lOSB for the value IS.SUC. 
Then test the full word for IS.CR, IS. ESC, or IS. ESQ. (If the full 
word tests equal to IS.SUC, then its high-order byte is 0, indicating 
byte-count termination of the read.) 

The "error" return IE. EOF may be considered to indicate a successful 
read, because characters can be returned to the task's buffer. 

The three errors in Table 3-8 with SE.xxx codes are returned by the 
SF.GMC and SF.SMC QIOs. They are characterized by IE.AB0&377 in the 
low-order byte of the first lOSB word. The high-order byte contains 
the error code. The second lOSB word contains an offset (starting 
from 0) to the byte in error in the QIOs stadd buffer. 



3.5 CONTROL CHARACTERS AND SPECIAL KEYS 

This section describes the meanings of special terminal control 
characters and keys for RSX-llM. Note that the driver does not 
recognize control characters and special keys during a Read All 
request (lO.RAL) , and recognizes only some of them during a Read with 
Special Terminators (lO.RST). 
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Table 3-8 
Terminal Status Returns 



Code 



Reason 



IE. EOF 



Successful completion on a read with end-of-file 



IS = sue 



The line of input read from the terminal was 
terminated with the end-of-file character CTRL/Z. 
The second word of the I/O status block contains 
the number of bytes read before CTRL/Z was seen. 
The input buffer contains those bytes. 

Successful com.pletion 



The operation specified in the QIO directive was 
completed successfully. If the operation involved 
reading or writing, you can examine the second word 
of the I/O status block to determine the number of 
bytes processed. The input buffer contains those 
bytes. 



IS.CR 



Successful completion on a read 



The line of input read from the terminal was 
terminated by a carriage return. The input buffer 
contains the bytes read. 



IS. ESC 



Successful completion on a read 



The line of input read from the terminal was 
terminated by an Altmode character. The input 
buffer contains the bytes read. 



IS. ESQ 



Successful completion on a read 



IS.PND 



The line of input read from the terminal was 
terminated by an escape sequence. The input buffer 
contains the bytes read and the escape sequence. 

I/O request pending 

The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 



IE. ABO 



Operation aborted 

The specified I/O operation was canceled by lO.KIL 
while in progress or while in the I/O queue. The 
second word of the lOSB shows how many bytes were 
processed before the kill took effect. Note that 
the SE.xxx error codes are characterized by IE.ABO& 
377 in the low-order byte of the first word of the 
lOSB. 



IE. BAD 



Bad parameter 






is too big (that is, greater than 255 bytes on 
systems supporting variable-length buffers or 
greater than 80 on systems that do not) . 



(continued on next page) 
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Table 3-8 (Cont.) 
Terminal Status Returns 



Code 



Reason 



lE.DAA Device already attached 

The physical device unit specified in an 10. ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. If 
the attach specified TF.AST or TF.ESQ, these 
subfunction bits have no effect. 

lE.DNA Device not attached 

The physical device unit specified in an lO.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks. 

lE.DNR Device not ready 

The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. This code is returned to indicate one 
of the following conditions: 

• A time-out occurred on the physical device unit 
{that is, an interrupt was lost). 

• An attempt was made to perform a function on a 
remote DHll or DZll line without carrier 
present. (The line is hung up.) 

lE.IES Invalid escape sequence 

An escape sequence was started but escape-sequence 
syntax was violated before the sequence was 
completed. See Section 3.6.4. 

IE. IPC Illegal function 

A function code specified in an I/O request was 
illegal for terminals; or, the function code 
specified was a SYSGEN option not selected for this 
system. 

IE. NOD Buffer allocation failure 

System dynamic storage has been depleted, and there 
was insufficient space available to allocate an 
intermediate buffer for an input request. 

(continued on next page) 
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Table 3-8 (Cont.) 
Terminal Status Returns 



Code 



lE.OFL 



IE. PES 



lE.PRI 



lE.RSU 



lE.SPC 



SE.BIN 



SE.NIH 



SE.VAL 



Reason 



Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 



Partial escape sequence 

An escape sequence was 
space was exhausted 
completed. See Section 

Privilege violation 



started, but read-buffer 
before the sequence was 
3.6.4.3. 



In a multiuser system, a nonprivileged task either 
issued an lO.WBT or directed an SF.SMC to a 
terminal other than its own TIO:. 

Resource in use 

The prompt of an 10. RPR, or a break-through write, 
was in progress when an lO.WBT was issued. Reissue 
the 10. WET later. 

Illegal address space 

The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task 
was specified. 



Alternately, a byte count of 



The new value specified for a terminal 
characteristic in an SF.SMC request was not or 1. 
(Characteristics other than TC.TTP — see Table 
3-5.) 

A terminal characteristic other than those in Table 
3-5 was named in an SF.GMC or SF.SMC request; or, 
a task attempted to assert TC.PRI. 

The new value specified in an SF.SMC request for 
the TC.TTP terminal characteristic was not one of 
those listed in Table 3-6, or the baud rate (speed) 
specified is not valid. 
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3.5.1 Control Characters 

A control character is input from a terminal by holding the control 
key (CTRL) down while typing one other key. Two of the control 
characters described in Table 3-9, CTRL/U and CTRL/Z, are echoed on 
the terminal as ^U and "2, respectively. Other control characters are 
recognized by the terminal driver, but are not printing characters and 
therefore are not echoed. 



Table 3-9 
Terminal Control Characters 



Character 



Meaning 



CTRL/C 



CTRL/I 

CTRL/J 
CTRL/K 

CTRL/L 

CTRL/M 



Typing CTRL/C repeatedly is the way to get a 
terminal's attention. Normally, typing CTRL/C 
causes unsolicited input on that terminal to be 
directed to the Monitor Control Routine (MCR) . 
"MCR>" echoes when the terminal is ready to accept 
unsolicited input. When the unsolicited input 
completes, it is passed to MCR. 

If the last item typed on the terminal was CTRL/S 
(suspend output) , then CTRL/C restarts suspended 
output and directs subsequent input to MCR. 

If the hold-screen mode option has been selected at 
SYSGEN, and if the terminal is a VT5x or VT61 in 
hold-screen mode, then typing a string of CTRL/Cs 
eventually removes the terminal from hold-screen 
mode. 

Not all CTRL/Cs act to get MCR's attention, 
CTRL/Cs are directed to a task if the task has 
attached a terminal and has specified an 
unsolicited-input-character AST. See the discussion 
on unsolicited-input-character ASTs, Section 
3.3.2.1. CTRL/Cs also go to a task if an lO.RAL 
(Read All) or lO.RST (Read with Special 
Terminators) is posted. 

Typing CTRL/I or TAB initiates a horizontal tab, 
and the terminal spaces to the next tab stop. Tabs 
at every eighth character position are simulated by 
the terminal driver. 

Typing CTRL/J is equivalent to typing the LINE FEED 
key on the terminal. 



Typing CTRL/K initiates a vertical tab, and 
terminal performs four line feeds. 



:he 



Typing CTRL/L initiates a form feed, and the 
terminal performs eight line feeds. Paging is not 
performed. 

Typing CTRL/M is equivalent to typing the carriage 
RETURN key on the terminal (see Section 3.5.2). 



(continued on next page) 
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Table 3-9 (Cont.) 
Terminal Control Characters 



Character 



Meaning 



CTRL/0 



CTRL/Q 
CTRL/R 



CTRL/S 



CTRL/U 



CTRL/Z 



sent to a 
For attached 

and output 
any of the 



Typing CTRL/0 suppresses output being 
terminal by the current I/O request, 
terminals, CTRL/0 remains in effect, 
continues to be suppressed until 
following occurs: 

1. The terminal is detached. 



2. Input is entered. 

3. Another CTRL/0 character is typed. 

4. An lO.CCO, lO.WBT, or 10. RPR is processed. 

For unattached terminals, CTRL/0 suppresses output 
for only the current output buffer (generally one 
line) . 

(SYSGEN option.) Typing CTRL/Q resumes terminal 
output previously suspended by means of CTRL/S. 



(SYSGEN option.) Typing 
results in the echo o 
incomplete (unprocessed) 
were input are expande 
rubouts is shown. On har 
allows you to verify 
rubouts in an input line 
for CRT terminals when th 
and CRT rubout SYSGEN opt 
(see Section 3.8). For 
the leftmost character on 
of a wrapped input li 
cursor does not move to 
displayed line. In th 
input line and the cursor 



CTRL/R on a terminal 
f CR/LF followed by the 
input line. Any tabs that 
d and the effect of any 
d-copy terminals, CTRL/R 
the effect of tabs and/or 
CTRL/R is also useful 
e automatic-cariage-return 
ions have been selected 
example, after rubbing out 

the second displayed line 
ne, you will find that the 
the right of the first 
is case, CTRL/R brings the 

back together again. 



(SYSGEN option.) Typing CTRL/S causes terminal 
output to be suspended. Output is resumed by 
typing CTRL/Q or CTRL/C. 

Typing CTRL/U before typing a line terminator 
causes previously typed characters to be deleted 
back to the beginning of the line. The system 
echoes this character as "U followed by a carriage 
return and a line feed. This allows you to retype 
the line. 



Typing CTRL/Z indicates 
current terminal input, 
and other system tasks 
complete and the task 
echoes this character as 
return and a line feed. 



an end-of-file for the 
It signals MAC, PIP, TKB, 
that terminal input is 
should exit. The system 
"Z followed by a carriage 
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3.5.2 Special Keys 

The Escape, carriage RETURN, and RUBOUT keys have special significance 
for terminal input, as described in Table 3-10. A line can be 
terminated by an ESCape (or Altmode) character, by a carriage RETURN, 
by CTRL/Z, or by completely filling the input buffer (that is, by 
exhausting the byte count before a line terminator is typed) , The 
standard buffer size for a terminal can be determined by issuing a GET 
LUN INFORMATION system directive and examining Word 5 of the 
information buffer. Another way is to type the MCR command "SET 
/BUF=TI:". 



3.6 ESCAPE SEQUENCES 

Escape sequences are strings of two or more characters beginning with 
33 octal. Some terminals generate an escape sequence when a special 
key is pressed (for example, the PFl key on the VTIOO) . On any 
terminal, an escape sequence may be generated manually by typing 
ESCape and the appropriate following characters. 

Escape sequences provide a way to pass input to a task without 
interpretation by the operating system. This could be done with a 
number of 1-character Read Alls, but escape sequences allow a neater 
way to accomplish it (they can be read with ordinary lO.RLBs) . 

Most DIGITAL software currently does not employ escape sequences. The 
specifics provided here are for the benefit of users who wish to take 
advantage of escape sequences in their own tasks. 



3.6.1 Definition 

An escape sequence is defined as follows: 
ESC [int] , . . [int] fin 



ESC 



int 



The result of pressing the ESCape key, a byte (character) of 
33(8) . 



An "intermediate character" in the range 40(8) to 57(8). This 
range includes the character "space" and 15 punctuation marks. 
An escape sequence may contain any number of intermediate 
characters, or none. 

fin 

A "final character" in the range 60(8) to 176(8). This range 
includes upper- and lowercase letters, numbers, and il3 
punctuation marks. 

There are four exceptions to this general definition discussed in 
Section 3.6.5. 
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Table 3-10 
Special Terminal Keys 



Key 



Meaning 



Escape 



If escape sequences are not recognized, typing 
Escape or Altmode signals the terminal driver that 
there is no further input on the current line. 
This line terminator allows further input on the 
same line, because the carriage or cursor is not 
returned to the first column position. 

If escape sequences are recognized, ESCape signals 
the beginning of an escape sequence. See Section 
3.6, 



RETURN 



Typing RETURN terminates the current line and 
causes the carriage or cursor to return to the 
first column on the line. 



RUB OUT 



Typing RUBOUT deletes the last character typed on 
an input line. Only characters typed since the 
last line| terminator may be deleted. Several 
characters can be deleted in sequence by typing 
successive RUBOUTs. 



The first RUBOUT echoes as a backslash (\) , 
followed by the character that has been deleted. 
Subsequent RUBOUTs cause only the deleted character 
to be echoed. The next character typed that is not 
a RUBOUT causes another backslash, followed by the 
new character, to be echoed. The following example 
illustrates rubbing out ABC and then typing CBA: 

ABC\CBA\CBA 

The second backslash is not displayed if a line 
terminator is typed after rubbing out the 
characters on a line, as in the following: 

ABC\CBA 

(SYSGEN option.) At SYSGEN time you may elect to 
support a "CRT rubout" feature. This feature 
applies to a terminal only after a SET MCR 
directive has been issued: 



SET /CRT=Tl! 



(Note: See Sec 


SET can 


oe a 


function.) 


When 


character 


(if 


input line 


and 


If the 1 


ast 


backspaces 


are 


character 


posi 


long input 


line 


automatic- 


:;arri 


erases the 


last 


cursor is 


not 


must be used to 


contents o 


f the 



tion 3.3.2.12 for another way this 

ccomplished, with the SF.SMC QIO 

a RUBOUT is struck, the last typed 

any) is removed from the incomplete 

backspace-space-backspace is echoed. 

typed character was a tab, enough 

issued to move the cursor to the 

tion before the tab was typed. If a 

was split, or "wrapped," by the 

age-return option, and a RUBOUT 

character of a previous line, the 

moved to the previous line. CTRL/R 

resynchronize the display with the 

incomplete input line. 
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3.6.2 Prerequisites 

Two prerequisites must be satisfied before escape sequences can be 
received by a task. 

First, the task must "ask" for them by issuing an 10. ATT and invoking 
the subfunction bit TF.ESQ. 

Second, the terminal must be declared capable of generating escape 
sequences. This may be done with an MCR SET command: 

SET /ESCSEQ=TI: 

An alternative way to tell the driver that the terminal can generate 
escape sequences is by issuing the Set Multiple Characteristics QIO. 
See Section 3.3.2.13. 

If either of these prerequisites is not satisfied, the ESC character 
is treated as a line terminator. If both prerequisites are satisfied, 
then an additional feature results. CTRL/SHIFT/0 (37(8)) may be used 
as an Altmode.-^ 

This character does not act as an Altmode from a terminal that cannot 
generate escape sequences. 



3.6.3 Characteristics 

Escape sequences always act as line terminators. That is, an input 
buffer may contain other characters that are not part of an escape 
sequence, but an escape sequence always comprises the last characters 
in the buffer. 

Escape sequences are not echoed. However, if a non-CRT rubout 
sequence is in progress, it is closed with a backslash when an escape 
sequence is begun. 

Escape sequences are not recognized in unsolicited input streams. 
Neither are they recognized in a Read with Special Terminators 
(subfunction bit TF.RST) nor in a Read All (subfunction bit TF.RAL) . 



3.6.4 Escape Sequence Syntax Violations 

A violation of the syntax defined in Section 3.6.1 causes the driver 
to abandon the escape sequence and to return an error (lE.IES). 



3.6.4.1 DEL or RUBOUT (177(8)) - The character DEL or RUBOUT is not 
legal within an escape sequence. Typing it at any point within an 
escape sequence causes the entire sequence to be abandoned and deleted 



1. An Altmode is a line terminator that does not cause the cursor to 
advance to a new line. On terminals that cannot generate escape 
sequences, the ESCape key acts as an Altmode. So do the characters 
175(8) and 176(8), if the terminal has not been declared lowercase 
(MCR command SET /LOWER). If the terminal is lowercase, then these 
characters represent right-brace and tilde, respectively. 
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from the input buffer. Thus, use DEL or RUBOUT to abandon an escape 
sequence, if desired, once you have begi 
enter : 



(un it. For example, if you 



AB ESC " DEL CR 

the buffer contains "AB" and the I/O status block looks like the 
following : 



lOSB 



IS.CR 



3.6.4.2 Control Characters (0-37(8)) - The reception of any character 
in the range to 37(8) (with four exceptions — see footnotel) is a 
syntax violation that terminates the read with an error (lE.IES). For 
example, entering: 



ESC ! CTRL/SHIFT/0 

results in a buffer that contains these three characters and 
status block that is similar to the following: 



an 



lOSB 



lE.IES 



I/O 



3.6.4.3 Full Buffer - A syntax error results when an escape sequence 
is terminated by running out of read-buffer space, rather than by 
reception of a final character. The error IE. PES is returned. For 
example, after a task issues an lO.RLB QIO with a buffer length of 2, 
and you type: 

ESC ! A 

the buffer contains "ESC !", and the I/O status block contains: 

lOSB 



IE. PES 



The "A" is treated as unsolicited input. 



1. Four control characters are allowed: CTRL/Q, CTRL/S, CTRL/C, and 
CTRL/0. These characters are handled normally by the operating system 
even when an escape sequence is in progress. For example, entering: 

ESC CTRL/S A 



gives: 



lOSB 



IS. ESQ 



with the side effect of turning off the output stre 



am. 



3-25 



HALF-DUPLEX TERMINAL DRIVER 



3.6.5 Exceptions to Escape-Sequence Syntax 

Four "final characters" that normally would terminate an escape 
sequence are treated as special cases by the terminal driver. These 
special cases exist for historical compatibility reasons. Three of 
these characters are: ; (73(8)), ? (77(8)), and (117(8)). The 
syntax for escape sequences that contain these four characters as 
intermediates is: 

ESC ; [int] [int] fin 

ESC ? [int] [int] fin 

ESC [int] . .. [int] finl 

int => 40-57 (8). 
fin => 60-176 (8). 
finl => 100-176 (8). 

The fourth exception to the general syntax given in Section 3.6.1 
involves the "final character" Y (131(8)). Historically (for example, 
in the VT52) , ESC Y has been used to signal the cursor position. It 
is followed by two numbers signifying column and row positions: 

ESC Y colpos rowpos 

where colpos and rowpos are both characters in the range 40-176(8). 
They represent bias-40 numbers: colpos = 40 corresponds to column 0, 
and so forth. 



3.7 VERTICAL FORMAT CONTROL 

Table 3-11 summarizes the meanings of all characters used for vertical 
format control on the terminal. Any one of these characters can be 
specified as the value of the vfc parameter in the functions lO.WLB, 
lO.WVB, lO.WBT, 10. ceo, or 10. RPR. 



Table 3-11 
Vertical Format Control Characters 



Octal 
Value 



40 



60 



61 



Character 



blank 



Meaning 



SINGLE SPACE - Output a line feed, print the 
contents of the buffer, and output a carriage 
return. Normally, printing immediately 
follows the previously printed line. 



DOUBLE SPACE - Output two line 
the contents of the buffer, 
carriage return. Normally, 
contents are printed two 
previously printed line. 



feeds, print 

and output a 

the buffer 

lines below the 



PAGE EJECT - Output eight line feeds (or, if 
the terminal is an LA180S, output a form 
feed), print the contents of the buffer, and 
output a carriage return. 



(continued on next page) 
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Table 3-11 (Cont.) 
Vertical Format Control Characters 



Octal 
Value 


Character 


Meaning 


53 
44 

00 


+ 

$ 

null 


OVERPRINT - Print the contents of the buffer 
and output a carriage return, normally 
overprinting the previous line. 

PROMPTING OUTPUT - Output a line feed and 
print the contents of the buffer. This mode 
of output is intended for use with a terminal 
on which a prompting message is output, and 
input is then read on the same line. 

INTERNAL VERTICAL FORMAT - Print the buffer 
contents without addition of vertical format 
control characters. In this mode, more than 
one line of guaranteed contiguous output can 
be printed for each I/O request. 



All other vertical format control characters are interpreted as blanks 
(40(8)). 



3.8 FEATURES AVAILABLE BY SYSGEN OPTION 

A number of terminal-driver features are available as options at the 
time the RSX-llM system is generated (see the RSX-llM System 
Generation and Management Guide or RSX-llS System Generation and 
Installation Guide , as appropriate) . Some that have been mentioned 
previously in the text are: 

• All the device-specific QIO functions 

• Special keys 

- CTRL/S — Suspend output 

CTRL/Q — Resume suspended output 

- CTRL/R — Write incomplete input buffer 

- CRT rubout 

• Escape sequences 

Other features that you may select at SYSGEN time are described in the 
following sections. 



3.8.1 Automatic Carriage Return 

By SYSGEN option, all terminals in a system may be set to "wrap 
around," on input and output, after a specified number of columns. If 
this option is selected, the number of characters per line is 
determined on a terminal-by-terminal basis. An MCR SET command is 
used to specify the wrap-around column, n: 

>SET /BUF=TI:n 
> 
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(Note that n is an octal number by default. Type an explicit decimal 
point to enter a decimal number.) After SYSGEN and before this SET has 
been done for a given terminal, the default column width is 72 
(decimal) . 

The SET /BUF command used without an argument is an enquiry that 
returns the current buffer width for a terminal: 

>SET /BUF=TI: 

BUF=TI0:00072. 

> 

A task can determine the buffer width by issuing a Get LUN Information 
directive and examining word 5. 

After the SET has been done, typing the n+lst character results in a 
CR/LF being output before the n+lst character is echoed (at the 
leftmost character position of the next line). There is still only 
one input line, but it is displayed on two lines on the terminal. 

Output also wraps around after column n. This is undesirable for some 
applications. To disable wrap-around, set the buffer to some number 
greater than the terminal's column width. Output — and input 
too — beyond the column width will then overprint at the right 
margin. Wrap-around is also disabled when executing the lO.WAL 
function (see Section 3.10.11), because the driver does not keep track 
of the cursor's position. 

It is possible to lose track of where you are in the input buffer if 
both the automatic carriage return and the CRT rubout features have 
been selected at SYSGEN. If, while rubbing out text on a wrapped 
line, you rub out the first character on that line, the cursor will 
not back up to the previous line. In order to resynchronize the 
cursor with the contents of the incomplete input buffer, type CTRL/R 
(if this option has been selected). 

It is also possible to cause wrap-around to malfunction. This can 
occur when more than 255(10) characters are output without an 
intervening carriage return. This condition is possible because the 
driver maintains a byte location with the current cursor position; 
thus, counts greater than 255(10) are truncated, and the cursor count 
will be invalid until the next carriage return is received. 



3.8.2 Variable-Length Buffering 

If this user-transparent SYSGEN option is selected, up to 255(10) 
characters may be read from a terminal. The terminal driver allocates 
an Executive buffer the same size as the read request. 

If the variable-length option is not chosen, any number of characters 

may be read from a terminal, but a maximum of 80(10) are transferred 

to the task issuing the read request. An Executive buffer of 80(10) 
characters is always allocated. 

Note that, whether variable-length buffering is selected or not, a 
maximum of 80(10) characters may be directed to MCR as unsolicited 
input. 
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3.8.3 Task Buffering of Received Characters 

This user-transparent SYSGEN option causes characters read from the 
terminal to be sent directly to the reading task's buffer. With this 
option, no Executive buffer need be allocated, and the completed input 
line need not be transferred to the task's buffer. This option, 
however, does not necessarily reduce system overhead. In a mapped 
system, each character must be mapped to the task's buffer. If 
Executive buffering was used, the mapping is done once and then all 
the characters are transferred. For the half-duplex terminal driver, 
the Executive buffers only input except for the prompt output on an 
10. RPR request. 

Task buffering may be overridden by checkpointing. If a task is 
checkpointable, an Executive buffer is allocated in the normal way and 
the task is made eligible for checkpointing by any task, regardless of 
priority, while the read proceeds. (Checkpointing only occurs when 
there is another task that can be made active.) Since 
checkpointability is a dynamic quality controlled by the task, the 
user retains control over the resource trade-off. 



3.8.4 LA30-P Support 

This option provides a 1-byte software buffer for terminal input from 
an LA30-P. Because LA30-PS communicate with RSX-llM by a 
single-buffered hardware interface, the echoing of an input character 
may block the reception of the next input character. This is because 
a character is normally discarded by the terminal driver if it is 
received before the echo of the previous character completes. The 
SYSGEN option for LA30-P support (transparent to the user) will buffer 
the second character in the software. 

This option should not be chosen at SYSGEN if there are no LA30-Ps in 
the system. 



3.9 TERMINAL INTERFACES 

This section summarizes the characteristics of the four types of 
standard communication-line interfaces supported by RSX-llM. All four 
Interfaces support parity, but RSX-llM does not. 



3.9.1 DHll Asynchronous Serial Line Multiplexer 

The DHll multiplexer Interfaces up to 16 asynchronous serial 
communications lines for terminal use. The DHll supports programmable 
baud rates. Input and output baud rates may differ; the input rate 
may be set to baud, thus effectively turning off the terminal. The 
DMll-BB option may be Included to provide modem control for dial-in 
lines. These lines must be Interfaced by means of a full duplex modem 
(for example, in the United States, a Bell 103A or equivalent modem). 

The direct memory access (DMA) capability of the DHll is not supported 
by the RSX-llM terminal driver. 
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3.9,2 DJll Asynchronous Serial Line Multiplexer 

The DJll multiplexer interfaces as many as 16 asynchronous serial 
lines to the PDP-11 for local terminal communications. The DJll does 
not provide a dial-in capability, but supports jumper-selectable baud 
rates. 



3.9.3 DLll Asynchronous Serial Line Interface 

The DLll supports a single asynchronous serial line and handles 
communication between the PDP-11 and a terminal. A number of standard 
baud rates are available to DLll users. Four versions of the DLll 
interface are supported by RSX-llM for terminal use: DLll-A, DLll-B, 
DLll-C, and DLll-D. The DLll-E is supported by the full-duplex 
terminal driver described in Chapter 2, and by the message-oriented 
communication drivers described in Chapter 11. 



3.9.4 DZll Asynchronous Serial Line Multiplexer 

The DZll multiplexer interfaces up to eight asynchronous serial 
communication lines for use with terminals. It supports programmable 
baud rates; however, input and output speeds must be the same. The 
DZll can control a full duplex modem in auto-answer mode. 



3.10 PROGRAMMING HINTS 

This section contains information relevant to users of the terminal 
driver. 



3.10.1 Terminal Line Truncation 

If automatic carriage return has not been selected at SYSGEN, and if 
the number of characters to be printed exceeds the line length of the 
physical device unit, then the terminal driver discards the excess 
characters until it receives one that instructs it to return to 
horizontal position 1. You can determine when this will happen by 
examining word 5 of the information buffer returned by the Get LUN 
Information system directive, or by typing "SET /BUF=TI:". 



3.10.2 Escape Code Conversion 

If escape sequences are not recognized, an ESCape or Altmode character 
code of 33, 175, or 176 is converted internally to 33 before it is 

returned to the user on input. 



3.10.3 RT02-C Control Function 

Because the screen of an RT02C Badge Reader and Data Entry Terminal 
holds only one line of information, special care must be taken when 
sending a control character (for example, vertical tab) to the RT02-C. 
Use lO.WAL (Write All) . 
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It is advisable to read without echoing when reading a badge with the 
RT02-C. Use lO.RAL or lO.RNE, and then write the received 
information. 



3.10.4 Checkpointing During Terminal Input 

If checkpointing during terminal input was selected as a SYSGEN 
option, a checkpointable task is stopped (and therefore eligible to be 
checkpointed) when trying to read. Therefore, a stratagem such as 
issuing a read followed by a mark-time does not work. The intent 
might be to time out the read if input is not received in a reasonable 
length of time. But the mark-time is not issued until the read 
completes. 

You can circumvent this behavior by disabling checkpointing for the 
read. This is not a desirable solution because it forces a task to 
remain in memory during the entire read. This defeats the purpose of 
selecting the checkpoint-during-terminal-input option. 



3.10.5 Time Required for lO.KIL 

An lO.KIL request may take up to 1 second to succeed, because an 
internal mark-time mechanism is used to generate a software interrupt 
to get into a clean state. The I/O may reach a state in which the 
kill can complete within this time (for instance, if a hardware 
interrupt is received). If not, the request is killed after 1 second. 



3.10.6 Use of lO.WVB 

We recommend that you routinely use lO.WVB, instead of lO.WLB, when 
writing to a terminal. If the write actually goes to a terminal, the 
Executive converts your lO.WVB into lO.WLB. However, if the LUN has 
been redirected to some inappropriate device — a disk, for 
example — using an lO.WVB will be rejected because a file is not open 
on the LUN. This prevents privileged tasks from overwriting block 
zero of the disk (the boot block) . 

Note that any subfunction bits specified in the lO.WVB request (for 
example, TF.CCO, TF.WAL, or TF.WBT) are stripped off when the QIO is 
converted to an lO.WLB. 



3.10.7 Remote DHll and DZll Lines 

All remote DHll lines in a system are answered at the same baud rate. 
All remote DZll lines are also answered at the same rate, which may 
differ from the DHll rate. These rates are specified at system 
generation. 

Before a remote DHll or DZll line is answered, the driver clears 
certain of the terminal characteristics (see Table 3-5) that may have 
been set by an MCR SET command or by an SF.SMC QIO. The 
characteristics cleared are: TC.SCP, TC.ESQ, TC.HLD, TC.SMR, and 
TC.TTP. (Clearing TC.TTP means that a terminal type of "unknown" is 
returned to an SF.GMC request.) Also, buffer size is set to 73. 
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A DZll remote line must be declared to be remote before the terminal 
driver will correctly handle the modem. This is done with the MCR 
command SET /REMOTE=TI:. 

NOTE 

Because of the few modem signals that 
the DZll handles and the lack of 
interrupt support provided for those 
signals, the DZll may not adequately 
handle telephone exchange requirements 
in all countries. 



3.10.8 High-Order Bit on Output 

Setting the high-order bit of an output byte causes it to be 
transmitted but not interpreted by the driver. 



3.10.9 Side Effects of Setting Characteristics 

Some of the characteristics that a task may set, or that you may set 
from a terminal, have side effects that should be noted. 

• TC.HLD — Unexpected behavior can result from a terminal in 
hold-screen mode if its reception rate is much greater than 
its transmission rate. (The DHll supports split baud rates.) 
In hold-screen mode the terminal sends a CTRL/S during 
reception of an output stream, when the screen is nearly full. 
Output is resumed -- another screen-full — when you type 
SHIFT/SCROLL (the terminal generates CTRL/Q) . Thus, no output 
is lost as a result of scrolling off the screen before you can 
read it. However, if the terminal's transmission rate is far 
below its reception rate, some unread output may scroll out of 
sight before the CTRL/S can be transmitted. 

A related point to note is that some terminals and interfaces 
are hardware buffered. This fact can cause obscure timing 
problems for tasks that try to implement hold-screen mode, 

• TC.SMR — If this characteristic is asserted (that is, if 
lower-/uppercase conversion is disabled by, for example, SET 
/LOWER=TI:), the two characters 175(8) and 176(8) are 
interpreted as [ (right-brace) and (tilde) , respectively. 
If TC.SMR is not asserted, these two characters act as 
Altmodes. That is, they act as line terminators that do not 
advance the cursor to a new line. Altmodes are jipt echoed. 



3.10.10 Unsolicited-Input-Character ASTs for Tasks Attaching Several 
Terminals 

For a task that attaches several terminals (for example, a reentrant 
language processor) , the handling of unsolicited input requires 
special care. When the terminal driver passes an unsolicited input 
character to a task, it does not pass any information about which of 
several terminals generated the character. The task must ascertain 
this for itself. 
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One solution is for the task to name uniquely the AST entry points for 
each attached terminal. Each separate AST then identifies its 
terminal before branching to a common routine that processes the 
unsolicited character. For example: 

ATTl: QIO$C 10. ATA, . . . , <UIC1> 

BR CONT 
ATT2: QIO$C 10. ATA, , , . , <UIC2> 

BR CONT 



UICl: MOV #1,-(SP) 

BR UIC 
UIC2: MOV #2,-(SP) 

BR UIC 



UIC: MOV (SP)+, INDEX 



3.10.11 Direct Cursor Control 

The terminal driver generally examines the output stream in order to 
keep track of the cursor's horizontal position (so that output can be 
wrapped around or discarded). Therefore, tasks that want to use 
direct cursor control should use lO.WALs. This prevents the terminal 
driver from inserting CR/LFs (that the task considers spurious) into 
the output stream. FORTRAN WRITE statements become lO.WVBs, which are 
interpreted by the driver. To prevent this, a FORTRAN task can use 
the CALL QIO routine or can issue carriage returns at frequent 
intervals (to make the driver think the cursor is always well to the 
left of the rightmost column, and therefore no CR/LFs need be emitted 
to keep the cursor on the screen) . 



3.10.12 DLll Receiver Interrupt Enable 

For hardware reasons, a DLll is susceptible to 
interrupt enable in its Receiver Status Register, 
the receiver interrupt bit causes the terminal 
requests but not to respond to input (for example, 
not echo input characters) . The terminal driver has 
recognizing the disabling. Therefore, it cannot 
must be reset with an MCR OPEN command, the console 
or a periodically rescheduled task. 



losing receiver 
The disabling of 
to print output 
the terminal does 
no mechanism for 
recover. The bit 
switch register. 



3.10.13 Loadable Driver Restrictions 

Checkpointing during terminal input, variable-length terminal buffer 
support, and escape sequence support require the presence of 
conw 1 1 lona j.xy assembled Executive support. If a loadable terminal 
driver supports one of these features and the Executive does not (or 
vice versa) , the best that can happen is an undefined global when the 
terminal driver is built. At worst, the system is corrupted. 
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CHAPTER 4 
VIRTUAL TERMINAL DRIVER 



4.1 INTRODUCTION 

The virtual terminal driver supports offspring task use of virtual 
terminals in RSX-llM-PLUS systems. Virtual terminals are not physical 
hardware devices; they are actually implemented in software through 
the use of data structures created by the RSX-llM-PLUS Executive. 
Virtual terminals are created by the Executive when requested by 
parent tasks with the Create Virtual Terminal directive. Virtual 
terminals are useful in batch processing and other processing 
environments in providing noninteractive terminal I/O support for 
offspring tasks, eliminating the need for operator intervention. 

Offspring task(s) "spawned" by or "connected" to the parent task that 
created the virtual terminal can perform terminal I/O operations with 
the virtual terminal in the same manner as with physical terminals. 
Virtual terminals differ from physical terminals in that they receive 
input from or output to a program (the parent task) , rather than from 
a keyboard or to a display (or printer) , respectively. 



4.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for virtual terminals. A setting of 1 indicates that the 
described characteristic is true for virtual terminals. 

Meaning 

Record-oriented device 
Carriage-control device 
Terminal device 
File-structured device 
Single-directory device 
Sequential device 
Reserved 
User— mode diagnostics supported 



Bit 


Setting 





1 


1 


1 


2 


1 


3 





4 





5 





6 
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it 


Setting 


8 





9 





10 





11 





12 





13 





14 





15 






Meaning 
Massbus device 
Unit software write-locked 
Input spooled device 
Output spooled device 
Pseudo device 

Device mountable as a communications channel 
Device mountable as a FILES-11 volume 
Device mountable 



Words 3 and 4 are undefined. Word 5 specifies the maximum byte count 
(that is, maximum buffer size) to which offspring requests will be 
truncated; this value is specified by the parent task in the Create 
Virtual Terminal system directive, as described in the RSX-llM/M-PLUS 
Executive Reference Manual. 



4.3 QIO MACRO 

Table 4-1 lists the standard and device-specific functions of the QIO 
macro that are valid for virtual terminals. 

Table 4-1 
Standard and Device-Specific QIO Functions for Virtual Terminals 



Format 


Function 


STANDARD FUNCTIONS: 




QIO$C 


10. ATT,. . . 


Attach device 


QIOSC 


lO.DET, . .. 


Detach device 


QIO$C 


lO.KIL, ... 


Cancel I/O request 


QIO$C 


lO.RLB, . . . ,<stadd,size> 


Read logical block 


QIO$C 


lO.RVB, . . . ,<stadd,size> 


Read virtual block 
(effects lO.RLB) 


QIO$C 


lO.WLB, . . . ,<stadd ,size,stat> 


Write logical block 


QIO$C 


lO.WVB, . . . ,<stadd,size,stat> 


Write virtual block 
(effects lO.WLB) 



(continued on next page] 
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Table 4-1 (Cont.) 
Standard and Device-Specific QIO Functions for Virtual Terminals 



Format 



DEVICE-SPECIFIC FUNCTIONS: 
QIO$C lO.STC, . . . ,<cb,sw2,swl> 



QIO$C SF.GMC, . . . ,<stadd ,size> 

QIO$C lO.GTS, . . . ,<stadd,size> 

QIO$C 10. RPR, . . . ,<stadd,size, [tmo] , 
pradd ,prsize,vfc> 

QIO$C SF.SMC, . . . ,<stadd,size> 



Function 



Set terminal characteristics 
(enable/disable intermediate 
I/O buffering, or return I/O 
completion status to 
offspring task) 

Get multiple characteristics 

Get terminal support 

Read logical block 
after prompt 

Set multiple characteristics 



size 



The size of the data buffer in bytes (must be greater than 0) . 
The buffer must be located within the addressing space of the 
parent or offspring task issuing the I/O request. 



stadd 



The starting address of the data buffer. The address must be 
word aligned for SF.GMC, 10. GTS, and SF.SMC; otherwise, it may 
be aligned on a byte boundary. 



Stat 



The I/O completion status code, specified by the parent task, 
that is issued by the virtual terminal driver in response to an 
offspring task's read request upon successful completion. 



cb 



Characteristic bits to become set, selecting the following 
virtual terminal functions: 



cb Value 





Bits Set 



none 



and 1 



Function 

Enable intermediate 
buffering in the Executive 
pool 

Return the specified 
virtual terminal I/O 
completion status to the 
requesting offspring task 



Disable 
buffering 



intermediate 



Return status for 
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swl 

The I/O completion code for I/O completion status, 

NOTE 

The sw2 and swl parameters are valid in 
the lO.STC function only when cb=l or 
cb=3. 

trao 

An optional time-out count (see below) . 
vfc 

A character for vertical format control. See Table 3-11. 

pradd 

The starting address of the prompt buffer, 
prsize 

The size of the prompt buffer in bytes. The buffer must be 
located within the address space of the offspring task issuing 
the I/O request. 



4.3.1 Standard QIO Functions 

4.3.1.1 10. ATT - This I/O function can be issued by offspring task 
tasks to attach the virtual terminal. (It is illegal for parent tasks 
to issue 10. ATT). Attaching a virtual terminal prevents other 
offspring tasks from executing I/O operations with the virtual 
terminal. However, parent task I/O requests are always serviced when 
issued . 



4.3.1.2 lO.DET - This I/O function can be issued by offspring tasks 
to detach the virtual terminal, making it available for use by other 
offspring tasks connected to the same parent task. (It is illegal for 
parent tasks to issue lO.DET.) 



4.3.1.3 lO.KIL - Parent and offspring tasks can issue lO.KIL to 
cancel I/O requests. An offspring task issuing lO.KIL can result in 
IE. ABO being returned to the parent task. 



4.3.1.4 lO.RLB, lO.RVB, lO.WLB, lO.WVB - These read and _ write 
functions execute requested I/O operations with virtual terminals in 
the same manner as with terminals described in Chapter 2, except as 
follows: 

1. The virtual terminal driver returns the tmo parameter of an 
offspring task's lO.RLB or lO.RVB request, or the vfc 
parameter of an offspring task's lO.WLB or lO.WVB request as 
a stack parameter on entry to the appropriate AST for the 
parent task. 
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The virtual terminal driver returns I/O completion status to 
the offspring task in response to successful completion of 
the offspring task's lO.RLB or lO.RVB request; however, the 
actual I/O completion status values returned are specified 
for data transfers in the third parameter word of the parent 
task's lO.WLB or lO.WVB response, or in the second and third 
parameters of the parent task's lO.STC function response when 
no data transfer is desired. 



4.3.2 Device-Specific QIC Function (lO.STC) 

The lO.STC function can be issued by parent tasks to enable/disable 
offspring task I/O buffering in secondary pool, or to force an 
appropriate I/O completion status for an offspring task read I/O 
request when no data transfer is desired. Both of these applications 
for the lO.STC function are described as follows. 

Parent tasks can use lO.STC to enable (or disable) intermediate 
buffering in secondary pool. Intermediate buffering, when enabled, is 
performed on offspring task virtual terminal read and write requests 
when the offspring task is checkpointable. 

Thus, offspring tasks can be stopped for virtual terminal I/O and 
checkpointed in a manner similar to that when physical terminals are 
used. Whenever the virtual terminal driver determines that 
intermediate buffering should not be used, offspring tasks that issue 
terminal requests become locked in memory until I/O completion; 
transfers occur directly between parent task and offspring task 
buffers without intermediate buffering in secondary pool. 

In addition to the conditions that permit intermediate buffering (when 
specified) , one condition can automatically disable intermediate 
buffering of the parent task. If the buffer size specified in the 
Create Virtual Terminal directive exceeds the maximum size specified 
at system generation time (512(10) maximum), intermediate buffering is 
disabled. 

The second application for lO.STC is to allow the virtual terminal 
driver to return an appropriate I/O completion status in response to 
an offspring task read request. I/O status returned in this manner 
allows successful completion of the offspring task's request when the 
parent task determines that no data transfer is desired; this 
condition can occur, for example, when no data is available for input 
to the offspring task by the virtual terminal driver. When used in 
this manner, the lO.STC function must include three parameters, 
<cb,sw2,swl>, as follows: 



cb 



A value of 1 is specified to Indicate that the I/O completion 
status return to the offspring task is desired. 



NOTE 

If the virtual terminal is operating in full duplex mode, 
a cb value of 1 returns status for an offspring read 
request, and a cb value of 3 returns status for an 
offspring write request. 
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This parameter is the second word returned in the I/O completion 
status indicating the number of bytes read upon successful 
completion of an offspring task's read request. However, since 
no data transfer actually occurs, the value specified is 0; the 
byte count of specified in this function is legal (and 
desired) , whereas a byte count of in write operations is 
illegal (and will result in an error being returned to the parent 
task) . 



This parameter specifies the status code to be returned to the 
offspring task by the virtual terminal driver in the first word 
of the I/O completion status. This value is returned in the high 
byte and a value of +1 is returned in the low byte of the status 
word. Typical values and the status that each represent are 
listed as follows: 

Code Value Completion Status Indicated 

Successful completion 

Read terminated by carriage 
return 

Read terminated by an Altmode 

Read terminated by an escape 
sequence 



4.3.3 SF.GMC 

The Get Multiple Characteristics function returns information on 
terminal characteristics. This function can be issued by both the 
parent and the offspring tasks. The virtual terminal driver returns 
the characteristics that were set by the previous corresponding SF.SMC 
request. However, only the full duplex mode (TC.FDX) characteristic 
affects the operation of the virtual terminal driver. The SF.GMC 
function is provided only to maintain transparency to the offspring 
task. 

Valid virtual terminal characteristics are listed in Table 4-2. 



4.3.4 10. GTS 

The Get Terminal Support function returns a 4-word buffer of 
information specifying which features are a part of the virtual 
terminal driver. The virtual terminal driver provides the 10. GTS 
function only to maintain transparency to the offspring task. Table 
2-7 lists the options returned by the full duplex terminal driver. Of 
those listed, the virtual terminal driver returns the following: 

Word 1 — Fl.BUF, Fl.RPR, Fl.UTB, and Fl.VBF 

Word 2 — F2.SCH and F2.GCH 



IS. sue 


+ 1 


IS.CR 


15 


IS. ESC 


33 


IS. ESQ 


233 
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4.3.5 10. RPR 

The Read After Prompt (10. RPR) function can be issued only by the 
offspring task. When the offspring task issues this function, the 
function appears to the parent task as a separate write request 
followed by a read request. This function is described in Chapter 3. 



4.3.6 SF.SMC 

The SF.SMC function allows a task to set and reset the characteristics 
of a terminal. Both the parent and the offspring tasks may issue this 
function. The parent task may set virtual terminals to full duplex 
operation by using the SF.SMC function with the characteristics bit 
TC.FDX. When in full duplex mode, the virtual terminal driver 
attempts to process the offspring task's read and write requests 
simultaneously. In order to insure that these operations are 
overlapped, the parent task should minimize the amount of time it 
spends in AST state. 

The virtual terminal driver defaults to half duplex mode. 

Table 4-2 lists the characteristics that either the parent or the 
offspring task may set. 



Table 4-2 
Virtual Terminal Characteristics 



Bit Name 


Octal 
Value 


Meaning (If Asserted) 


Default 


Value 


TC . FDX 


64 


Full duplex mode 







TC.SCP 


12 


Terminal is a scope 







TC.SMR 


25 


Uppercase conversion 
disabled 







TC.TTP 


10 


Terminal type 








4.4 STATUS RETURNS 

The error and status conditions listed in Tables 4-3 and 4-4 are 
returned by the virtual terminal driver described in this chapter. 
The SE.NIH error is returned by the SF.GMC and SF.SMC functions. For 
this error, the low byte of the first word in the I/O status block 
contains IE. ABO. The second word in the I/O status block contains an 
offset (starting at 0) pointing to the erroneous byte in the stadd 
buffer. 
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Table 4-3 
Virtual Terminal Status Returns for Offspring Task Requests 



Code 



Reason 



IS. sue 



lE.IFC 



IE. ABO 



lE.SPC 



lE.UPN 



SE.NIH 



Successful completion of an offspring task read 
request results in an I/O completion status specified 
in a parent task QIO parameter being returned. 
Typically, the status information returned simulates 
a subset of I/O returns normally produced by the 
terminal drivers described in Chapter 2. 

Successful completion 

The operation specified in the QIO directive was 
completed successfully. The second word of the I/O 
status block indicates the number of bytes 
transferred on a write operation. 

Invalid function code 

The offspring task attempted a read or a write 
function and the parent task did not specify an AST 
address in its response to the requested I/O 
function, or the offspring task issued an lO.STC or 
other invalid function. 

Request terminated 

The offspring task issued lO.KIL or the parent task 
eliminated the virtual terminal unit. 

Illegal address space 

Part or all of the buffer specified for a read or 
write request was outside of the task's address 
space, or a byte count of was specified. 

Insufficient dynamic storage 

The driver could not allocate an AST block to notify 
the parent task of an offspring task request, or the 
driver could not allocate an intermediate buffer in 
the Executive pool. 

A terminal characteristic other than those in Table 
4-2 was specified, or an offspring task attempted to 
assert TC.FDX. 
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Table 4-4 
Virtual Terminal Status Returns for Parent Task Requests 



Code 



Reason 



IS. sue 



IE. EOF 



IE. BAD 



IE. DUN 



IE. IPC 



SE.NIH 



Successful completion 

The operation specified in the QIO directive was 
completed successfully. The second word of the I/O 
status block indicates the number of bytes 
transferred on a read or write operation. 

End of file encountered 

The lO.STC function was completed successfully. 

Bad parameters 

The parent task specified a buffer size that exceeded 
the system maximum specified at system generation 
time. 

Device not attachable 

An 10. ATT or lO.DET function was issued by the parent 
task. 

Invalid function code 

A read, write, or lO.STC function was issued without 
a pending offspring task request. This status can 
occur if the offspring task cancels a pending read or 
write request. This function code is also returned 
when lO.STC is issued to enable intermediate 
buffering on a virtual terminal unit whose buffer 

Create Virtual Terminal 
system maximum specified at 



virtual 
size, specified in the 
directive, exceeds the 
system generation time. 



A terminal characteristic other than those in Table 
4-2 was specified in an SF.GMC or SF.SMC request. 
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5.1 INTRODOCTION 

The RSX-llM disk drivers support the disks summarized in Table 5-1. 
Subsequent sections describe these devices in greater detail. 

All of the disks described in this chapter are accessed in essentially 
the same manner. Up to eight disks of each type (except RXOl, RX02, 
RX50, RD51, RC25, RLOl, RL02, RA60, RA80, or RA81) may be connected to 
their respective controllers. Disks and other file-structured media 
are divided logically into series of 256-word blocks. 



5.1.1 RFll/RSll Fixed-Head Disk 

The RFll controller/RSll fixed-head disk provides random access bulk 
storage. It features fast track-switching time and a redundant set of 
timing tracks. 



5.1.2 RS03 Fixed-Head Disk 

The RS03 (RH11-RH70 controller/RS03 fixed-head disk) is a fixed-head 
disk that offers speed and efficiency. With 64 tracks per platter and 
recording on one surface, the RS03 has a capacity of 262,144 words. 



5.1.3 RS04 Fixed-Head Disk 

The RS04 (RH11-RH70 controller/RS04 fixed-head disk) is similar to the 
RS03 disk and interfaces to the same controller, but provides twice 
the number of words per track by recording on both surfaces of the 
platter, and thus has twice the capacity. 



5.1.4 RP11/RP02 or RP03 Pack Disks 

The RPll controller/RP02 or RP03 pack disk consists of 20 data 
surfaces and a moving read/write head. The RP03 has twice as many 
cylinders, and thus double the capacity of the RP02. Only an even 
number of words can be transferred in a read/write operation. 
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Table 5-1 
Standard Disk Devices 



Controller/ 
Drive 


RPM 


Sees 


Trks 


Cyls 


Bytes/ 
Drive 


Decimal 
Blocks 


RFll/RSll 


1800 


— 


1 


128 


524,288 


1024 


RHXX/RS03 


3600 


641 


1 


64 


524,288 


1024 


RHXX/RS04 


3600 


64l 


1 


64 


1,048,576 


2048 


RP11E/RPR02 


2400 


10 


20 


200 


20,480,000 


40,000 


RP11C/RP03 


2400 


10 


20 


400 


40,960,000 


80,000 


RHXX/RM02 


2400 


32 


5 


823 


67,420,160 


131,680 


RHXX/RM03 


3600 


32 


5 


823 


67,420,160 


131,680 


RH70/RM05 


3600 


32 


19 


823 


256,196,608 


500,384 


RH11/RP04,RP05 


3600 


22 


19 


411 


87,960,576 


171,798 


RH70/RP06 


3600 


22 


19 


815 


174,423,040 


340,670 


RH70/RP07 


3600 


50 


32 


6302 


516,096,000 


1,008,000 


RH70/RM80 


3600 


31 


14 


5592 


124,214,272 


242,606 


RK11/RK05 


1500 


12 


2 


200 


2,457,600 


4800 


RLll/RLOl 


2400 


403 


2 


256 


5,242,880 


10,240 


RL11/RL02 


2400 


403 


2 


512 


10,485,760 


20,480 


RK611/RK06 


2400 


22 


3 


411 


13,888,512 


27,126 


RK611/RK07 


2400 


22 


3 


815 


27,810,800 


53,790 


RXll/RXOl 


360 


264 


1 


77 


256,256 


494 


RX211/RX02 


360 


26^ 


1 


77 


512,512 


988 


UDA50/RA80 


3600 


31 


14 


546 


121,325,568 


236,964 


UDA50/RA81 


3600 


51 


14 


1248 


456,228,864 


891,072 


UDA50/RA60 


3600 


42 


4 


2382 


204,890,112 


400,176 


RC2 5 


2850 


31 


2 


796 


26,061,824 


50,902 


RD51 


3600 


16 


4 


306 


10,027,008 


19,584 


RX50 


300 


10 


1 


80 


409,600 


800 



1. The RS03 has 54 words per sector; the RS04 has 128 
words/sector. 

2. The RP07 and the RM80 each have two additional CE cylinders. 

3. The RLOl and RL02 each have 128 words per sector. 

4. The RXOl has 54 words per sector; the RX02 has 128 words per 
sector . 
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5,1.5 RM02/RM03/RM05/RM80 Pack Disk 

The RM02/RM03, RM05, and RM80 are MASSBUS disk drives and adapters 
that use the existing MASSBUS controller, with a single head per 
surface, they provide a 1.2 megabyte-per-second data transfer rate. 
The RM03, RM05, and RM80 are used with the RH70 controller on 
PDP-11/70 systems. All other systems use the RM02 with the RHll 
controller. 



5,1,6 RP04, RP05, RP06 Pack Disks 

The RP04 or RP05 {RH11-RH70 controller/RP04 or RP05 pack disk) pack 

disks consist of 19 data surfaces and a moving read/write head. Both 

offer large storage capacity with rapid access time. The RP06 pack 

disk has approximately twice the capacity of the RP04 or RP05. The 

RP07 fixed-media disk has approximately 3 times the capacity of the 
RP0 6. 



5.1,7 RK11/RK05 or RK05F Cartridge Disks 

The RKll controller/RK05 DECpack cartridge disk is an economical 
storage system for medium- volume, random access storage. The 
removable disk cartridge offers the flexibility of large off-line 
capacity with rapid transfers of files between on- and off-line units 
without necessitating copying operations. The RK05F has twice the 
storage capacity of the RK05 and has a fixed (nonremovable) disk 
cartridge. 



5.1,8 RLll/RLOl or RL02 Cartridge Disk 

The RLOl is a low-cost, single-head per surface disk with a burst data 
transfer rate of 512 kilobytes per second. The storage capacity of 
the RL02 is twice that of the RLOl. 



5.1.9 RK611/RK06 or RK07 Cartridge Disk 

The RK611 controller/RK06 cartridge disk is a removable, random 
access, bulk-storage system with three data surfaces. The storage 
capacity is 6,944,256 words per pack. The system, expandable to eight 
drives, is suitable for medium to large systems. 

The RK611 controller/RK07 cartridge disk is generally similar to the 
RK611/RK06, except storage capacity is increased to approximately 
13,905,400 words per pack. Both RK06 and RK07 disks can use the same 
RK611 controller; mixing RK06 and RK07 disks on the same controller 
is permitted. 
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5.1.10 RXll/RXOl Flexible Disk 

The RXll controller/RXOl flexible disk is an economical storage system 
for low-volume, random access storage. Data is stored in twenty-six 
64-word sectors per track; there are 77 tracks per disk. Data may be 
accessed by physical sector or logical block. If logical or virtual 
block I/O is selected, the driver reads four physical sectors. These 
sectors are interleaved to optimize data transfer. The next logical 
sector that falls on a new track is skewed by six sectors to allow for 
track-to-track switch time. Physical block I/O provides no 
interleaving or skewing and provides access to all 2002 sectors on the 
disk. Logical or virtual I/O starts on track 1 and provides access to 
494 logical blocks. 



5.1.11 RX211/RX02 Flexible Disk 

The RX211 controller/RX02 flexible disk is an economical storage 
system for low-volume, random access storage. It is capable of 
operating in either an industry-standard, single-density mode (as 
stated for the RXll/RXOl flexible disk) , or a double-density mode (not 
industry standard) . In the single-density mode, each drive can store 
data exactly as stated in Section 5.1.10. In the double-density mode, 
data is stored in twenty-six 128-word sectors per track; there are 77 
tracks per disk. The RX211/RX02 operating in the single-density mode 
can read disks written by an RXll/RXOl flexible disk system. In 
addition, disks written by the RX211/RX02 operating in the 
single-density mode can be read by the RXll/RXOl flexible disk system. 



5.1.12 ML-11 bisk Emulator 

The ML-11 is a fast, random access, block-mode MOS memory system. The 
RSX-llM and RSX-llM-PLUS operating systems treat the ML-11 as a disk. 
However, since it is not a disk, the statistics in Table 5-1 do not 
apply. Unlike a disk, the number of bytes per drive varies. One 
ML-11 provides from 512 blocks to 8192 blocks of storage. 



5.1.13 ODA50/RA60/RA80/RA81 Disks 

The UDA controller is an intelligent disk controller, which contains a 
high-speed microprogrammed processor capable of performing all disk 
functions, including data handling, error detection and correction, 
and optimization of disk drive activity and data transfers. The types 
of drives that can be connected to the UDA50 controllers are the RA60 
disk drive, which has a removable pack, and the RA80 and RA81, both of 
which are fixed media drives. (For data capacities and rates, see 
Table 5-1.) Up to four of these drives can be connected to a UDA, in 
any desired combination. 

The UDA controller also has two addressable registers in the I/O page 
that are used for the initialization sequence and to initiate polling 
of command packet buffers in memory. In addition, this controller is 
also capable of carrying out an extensive self-test on power-up or 
initialization. 
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5.1.14 RC25 Disk Subsystem 

The RC25 Subsystem combines, in one package, a controller and a single 
disk drive that has a removable disk and a fixed disk. These disks 
reside in the drive as two separate logical units on a single spindle. 
Their size is the same. Both are single eight-inch disks with two 
surfaces, and both disks have the same data capacity. But 
mechanically they are different: One is a removable front-loading 
cartridge disk, while the other cannot be removed from the drive. The 
drive is designed with loadable Winchester type heads. 

An additional disk drive can be added to the RC25 Disk Subsystem, 
providing a dual spindle configuration with two fixed and two 
removable disks. The added-on disk drive is a slave to the disk 
subsystem that has the controller. 



5,1.15 RD51 Fixed 5.25 Disk/RX50 Flexible 5.25 Disk 

This subsystem is designed to serve a hard (RD)/flexible (RX) disk 
combination that can be used as a mass storage medium for small 
systems. The basic configuration for this mass storage scheme is an 
RD51 fixed disk drive and an RX50 flexible dual disk drive. In this 
configuration, the RD51 is the system device and the RX50 is used as a 
data device and/or as a backup. The RX50 dual disk is addressed as 
two separate units resulting in a basic configuration of three disk 
units. Also, another RD51 can be added to increase storage capacity. 
Some of the characteristics of the RD/RX drives are given in Table 5-1 
and in the following paragraphs. 

The RD51 disk drive is a 5.25 inch fixed disk with Winchester type 
heads. It has two disks with four data surfaces. The RD51 is soft 
sectored and field formattable. The headers for each sector contain 
the sector's cylinder number, head number, and sector number. The 
sector number is the logical sector number (0-15) that reflects the 
sector interleave of the disk. 

The RX50 dual diskette drive is a compact mass storage drive with two 
access slots. Each slot can hold a single-sided 5.25 flexible disk. 
These diskettes are firm sectored and are not field formattable. 
Every track has sectors numbered from 1 to 10. The two diskettes 
share the same head transport mechanism. 



5.2 GET LDN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for disks. A bit setting of 1 indicates that the 
described characteristic is true for disks. 
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Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported (device 
dependent) 

Device supports 22-bit direct addressing 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo-device 

Device mountable as a communications 
channel 

Device mountable as a FILES-11 volume 

Device mountable 



Words 3 and 4 of the buffer contain the maximum logical block number. 
Note that the high byte of U.CW2 is undefined. The user should clear 
the high byte in the buffer before using the block number. For the 
RA80 disk, these two words are undefined until the device has been 
accessed at least once. Word 5 indicates the default buffer size, 
which is 512 bytes for all disks. 



5.3 QIO MACRO 

This section summarizes the standard, and device-specific QIO 
functions for disk drivers. 



5.3.1 Standard QIO Functions 

Table 5-2 lists the standard functions of the QIO macro that are valid 
for disks. 



Bit 


Setting 








1 





2 





3 


1 


4 





5 





6 


1 


7 


X 


8 


X 


9 





10 





11 





12 





13 





14 


1 


15 


1 
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Table 5-2 
Standard QIO Functions for Disks 



Format 


Function 


QIO$C 


10. ATT, . 


• 


Attach device-'- 


QIO$C 


lO.DET, , 


• 


Detach device 


QIO$C 


lO.KIL,. 


» • 


Kill I/o2 


QIO$C 


lO.RLB,. 


. . ,<stadd,size, ,blkh,blkl> 


READ logical block 


QIO$C 


lO.RVB,. 


, . ,<stadd,size, ,blkh,blkl> 


READ virtual block 


QIO$C 


lO.WLB,. 


. . ,<stadd,size, ,blkh,blkl> 


WRITE logical block 


QIO$C 


lO.WLC,. 


. . ,<stadd ,size,,blkh,blkl> 


WRITE logical block 
followed by write 
check3 


QIO$C 


lO.WVB,. 


. . ,<stadd,size, ,blkh,blkl> 


WRITE virtual block 



1. In RSX-llM systems, only unmounted volumes may be attached; 
in RSX-llM-PLUS systems, only volumes mounted foreign may be 
attached. Any other attempt to attach a mounted volume will 
result in an lE.PRI status being returned in the I/O status 
doubleword . 

2. In-progress disk operations are allowed to complete when 
lO.KIL is received, because they take such a short time. I/O 
requests that are queued when lO.KIL is received are killed 
immediately. An IE. ABO status is returned in the I/O status 
doubleword. 

3. Not supported on RXOl or RX02 flexible disks. 



stadd 



size 



The starting address of the data buffer (must be on a word 
boundary) . 



The data buffer size in bytes (must be even, greater than 0, and, 
for the RP02 and RP03, also a multiple of four bytes') . 



blkh/blkl 



Block high and block low, combining to form a double-precision 
number that indicates the actual logical/virtual block address on 
the disk where the transfer starts; blkh represents the high 8 
bits of the address, and blkl the low 16 bits. 
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lO.RVB and lO.WVB are associated with file operations (see the 
IAS/RSX-11 I/O Operations Reference Manual ) . For these functions to 
be executed, a file must be open on the specified LUN if the volume 
associated with the LUN is mounted. Otherwise, the virtual I/O 
request is converted to a logical I/O request using the specified 
block numbers. 



NOTE 



When wr 
task m 
Control 
necessa 
the fil 
created 
the fil 
put an 
the end 
before 
. EXTND 
lAS/RSX 



iting a new 
ust explici 

System libr 
ry to rese 
e, or the fi 

with enough 
e. In addit 

appropriate 
-of-file bl 

closing the 

routine d 

11 I/O 



Manual. ) 



file using QIOs, the 
tly issue .EXTND File 
ary routine calls as 
rve enough blocks for 
le must be initially 

blocks allocated for 
ion, the task must 

value in the FDB for 
ock number (F.EFBK) 

file. (Refer to the 
escription in the 
Operations Reference 



Each disk driver supports the subfunction bit IQ.X: inhibit retry 
attempts for error recovery. The subfunction bit is used by ORing it 
into the desired QIO; for example: 

QIO$C lO.WLBlIQ.X,. .. ,<stadd,size, ,blkh,blkl> 

The IQ.X subfunction permits user-specified retry algorithms for 
applications in which data reliability must be high. 

The overlapped seek drivers for RSX-llM-PLUS support subfunction bit 
IQ.Q: queue the request immediately without doing a seek (that is, 
use implied seeks) . 



5.3.2 Device-Specific QIO Functions 

The device-specific functions of the QIO macro are valid for the RXOl 
only; they are shown in Table 5-3. 



Table 5-3 

Device-Specific Functions for the 

RX01,RX02, RLOl, and RL02 Disk Drivers 



Format 


Function 


QIO$C lO.RPB, . . . ,<stadd,size, , ,pbn> 
QIO$C 10. SEC,... 

QIO$C lO.SMD,. ..,<density,,> 

QIO$C lO.WDD, . . . ,<stadd,size, , ,pbn> 

QIO$C lO.WPB, . . . ,<stadd ,size, , ,pbn> 


Read physical block 

Sense diskette characteristics 
(RX02 only) 

SET media density (RX02 only) 

Write physical block (with deleted 
data mark) (RXOl and RX02 only) 

Write physical block 
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stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



size 



pbn 



The data buffer size in bytes must be even and greater than 0) 



The physical block number where the transfer starts (no 
validation will occur) . 



density 

The media density as follows: 

= single (RXOl-compatible) density 
2 = double density 

5.3.3 Device-Specific QIO Function for the RA80 

The RA80 driver supports the device-specific QIO function shown in 
Table 5-4. 



Table 5-4 
Device-Specific QIO Function for the RA80 Disk Driver 



Format 


Function 


QIO$C lO.RLC, . . . ,<stadd,size, ,blkh,blkl> 


Read Logical with Read Check 
modifier 



5.4 STATUS RETURNS 

The error and status conditions listed in Table 5-5 are returned by 
the disk drivers described in this chapter. 



Table 5-5 
Disk Status Returns 



Code 


Reason 


IS. sue 


Successful completion 






The operation specified in the QIO 


directive was 




completed successfully. The second 


word of the I/O 




status block can be examined to 


determine the 




number of bytes processed, if 


the operation 




involved reading or writing. 





(continued on next page) 
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Table 5-5 (Cont.) 
Disk Status Returns 



Code 



IS.PND 



IS.RDD 



IE. ABO 



lE.ALN 



lE.BLK 



Reason 



I/O request pending 

The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os . 

Deleted data mark read 

A deleted record was encountered while executing an 
lO.RPB function. The second word of the I/O status 
block can be examined to determine the number of 
bytes processed (RXOl and RX02 only) . 



Request aborted 

An I/O request was queued (not yet acted upon 
the driver) when an lO.KIL was issued. 

File already open 



by 



The task attempted to open a file on the physical 
device unit associated with specified LUN, but a 
file has already been opened by the issuing task on 
that LUN. 

Illegal block number 



lE.BBE 



An illegal logical block number was specified. 
This code would be returned, for example, if block 
4800 were specified for an RK05 disk, on which 
legal block numbers extend from through 4799. 
lE.BLK would also be returned if an attempt was 
made to write on the last track of an RK06 disk. 
(See Section 5.5.) 

Bad block error 



IE. BYT 



lE.DNR 



The disk sector (block) being read was marked as a 
bad block in the header word. 

Byte-aligned buffer specified 

Byte alignment was specified for a buffer, but only 
word alignment is legal for disk. Alternatively, 
the length of a buffer is not an appropriate number 
of bytes. For example, all RP03 and RP02 disk 
transfers must be multiples of four bytes. 

Device not ready 

The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. 



(continued on next page) 
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lE.FHE 



lE.IFC 



lE.NLN 



IE. NOD 



lE.OFL 



lE.OVR 



lE.PRI 
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Table 5-5 (Cont.) 
Disk Status Returns 



Reason 



Fatal hardware error 

The controller is physically unable to reach the 
location where input/output operation is to be 
performed. The operation cannot be completed. 

Illegal function 

A function code was specified in an I/O request 
that is illegal for disks. 

File not open 

The task attempted to close a file on the physical 
device unit associated with the specified LUN, but 
no file was currently open on that LUN. 

Insufficient buffer space 

Dynamic storage space has been depleted, and there 
was insufficient buffer space available to allocate 
a secondary control block. For example, if a task 
attempts to open a file, buffer space for the 
window and file control block must be supplied by 
the Executive. This code is returned when there is 
not enough space for this operation. 

Device off line 

The physical device unit associated with the LUN 
specified in the QIC directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 

Illegal read overlay request 

A read overlay was requested, and the physical 
device unit specified in the QIC directive was not 
the physical device unit from which the task was 
installed. The read overlay function can only be 
executed on the physical device unit from which the 
task image containing the overlays was installed. 

Privilege violation 

The task that issued the request was not privileged 
to execute that request. For disk, this code is 
returned if a nonpr ivileged task attempts to read 
or write a mounted volume directly (that is, using 
lO.RLB or lO.WLB) . Also, this code is returned if 
any task attempts to attach a mounted volume. 



(continued on next page) 
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Table 5-5 (Cont.) 
Disk Status Returns 



Code 


Reason 


lE.SPC 


Illegal address space 




The buffer specified for a read or write request 




was partially or totally outside the address space 




of the issuing task. Alternately, a byte count of 




was specified. 


lE.VER 


Unrecoverable error 




After the system's standard number of retries has 




been attempted upon encountering an error, the 




operation still could not be completed. For disk. 




unrecoverable errors are usually parity errors. 


lE.WCK 


Write check error 




An error was detected during the write check 




portion of an operation. 


lE.WLK 


Write-locked device 




The task attempted to write on a disk that was 




write-locked. 



When a disk I/O error condition is detected, an error is usually not 
returned immediately. Instead, RSX-llM attempts to recover from most 
errors by retrying the function as many as eight times. Unrecoverable 
errors are generally parity, timing, or other errors caused by a 
hardware malfunction. 



5.5 PROGRAMMING HINTS 

For the RK611 controller/RK06 or RK07 disk, the RLll controller/RLOl 
or RL02 disk, RM02 disk, RM03 disk, RM05 disk, RM80 disk, and RP07 
disk, the driver write-protects the last track of the cartridge. This 
track contains the factory-recorded bad-sector file. 
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DECTAPE DRIVER 



6 . 1 INTRODUCTION 

The RSX-llM DECtape driver supports the TCll-G dual DECtape controller 
with up to three additional dual DECtape transports. The TCll-G is a 
dual-unit, bidirectional, magnetic-tape transport system for auxiliary 
data storage. DECtape is formatted to store data at fixed positions 
on the tape, rather than at unknown or variable positions as on 
coventional magnetic tape. The system uses redundant recording of the 
mark, timing, and data tracks to increase reliability. Each reel 
contains 578 logical blocks. As with disk, each of these blocks can 
be accessed separately, and each contains 256 words. 



5.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characterics word) contains the following 
information for DECtapes. A bit setting of 1 indicates that the 
described characteristic is true for DECtapes, 

Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit addressing 

Unit software write-locked 



Bit 


Setting 








1 





2 





3 


1 


4 





5 





6 


1 


7 





8 





9 
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Bit Setting 



Meaning 



Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications 
channel 

Device mountable as a FILES-11 volume 

Device mountable 

Words 3 and 4 of the buffer contain the maximum LBN, Word 5 indicates 
the default buffer size, 512 bytes, for DECtape. 



10 





11 





12 





13 





14 


1 


15 


1 



6.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
the DECtape driver. 



6.3.1 Standard QIO Functions 

Table 6-1 lists the standard functions of the QIO macro that are valid 
for DECtape. 



Table 6-1 
Standard QIO Functions for DECtape 



Format 



QIO$C 10. ATT,.. 

QIO$C lO.DET,.. 

QIO$C lO.KIL,.. 

QIO$C lO.RLB,.. 

QIO$C lO.RVB,.. 

QIO$C lO.WLB,.. 

QIOSC lO.WVB,.. 



. ,<stadd,size, , ,lbn> 
. ,<stadd,size, , ,lbn> 
. ,<stadd,size, , ,lbn> 
. ,<stadd fSize, , ,lbn> 



Function 



Attach device! 

Detach device 

Kill I/O^ 

READ logical block (forward) 

READ virtual block (forward) 

WRITE logical block (forward) 

WRITE virtual block (forward) 



1. Only unmounted volumes may be attached. An attempt to attach a 
mounted volume will result in an lE.PRI status being returned in the 
I/O status doubleword. 

2. In-progress DECtape operations are allowed to complete when 
lO.KIL is received, unless the unit is not ready, because they take 
such a short time. I/O requests that are queued when lO.KIL is 
received are killed. An IE. ABO status is returned in the I/O status 
doubleword . 
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stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



size 



Ibn 



The data buffer size in bytes (must be even and greater than 0) 



The logical block number on the DECtape where the transfer starts 
(must be in the range 0-577) . 

lO.RVB and lO.WVB are associated with file operations (see the 
IAS/RSX-11 I/O Operations Reference Manu^) . For these functions to 
be executed ^T'file must be open on the specified LUN if the volume 
associated with the LUN is mounted. Otherwise, the virtual I/O 
request is converted to a logical I/O request using the specified 
block numbers. 



(5.3.2 Device-Specific QIO Functions 

The device-specific functions of the QIO macro that are valid for 
DECtape are shown in Table 6-2. 



Table 6-2 
Device-Specific Functions for DECtape 



Format 



QIO$C lO.RLV, . . . ,<stadd,size, , ,lbn> 
QIO$C lO.WLV, . . . ,<stadd,size, , ,lbn> 



Function 



READ logical block (reverse) 
WRITE logical block (reverse) 



stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



size 



Ibn 



The data buffer size in bytes (must be even and greater than 0) 



The transfer starts (must be in the range 0-577) 
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6.4 STATUS RETURNS 

The error and status conditions listed in Table 6-3 are returned by 
the DECtape driver described in this chapter. 



Table 6-3 
DECtape Status Returns 



Code 



Reason 



IS. sue 



IS.PND 



IE. ABO 



lE.ALN 



lE.BLK 



IE. BYT 



lE.DNR 



IE. IPC 



Successful completion 

The operation specified in the QIO directive was 
completed successfully. The second word of the I/O 
status block can be examined to determine the 
number of bytes processed, if the operation 
involved reading or writing. 

I/O request pending 

The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 

Request aborted 

An I/O request was queued (not yet acted upon by 
the driver) when an lO.KIL was issued. 

File already open 

The task attempted to open a file on the physical 
device unit associated with the specified LUN, but 
a file has already been opened by the issuing task 
on that LUN. 

Illegal block number 

An illegal logical block number was specified for 
DECtape. The number exceeds 577 (1101 (8)). 

Byte-aligned buffer specified 

Byte alignment was specified for a buffer, but only 
word alignment is legal for DECtape. Alternately, 
the length of the buffer is not an even number of 
bytes. 

Device not ready 

The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. 

Illegal function 

A function code was specified in an I/O request 
that is illegal for DECtape. 



(continued on next page) 
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Table 6-3 (Cont.) 
DECtape Status Returns 



Code 



Reason 



lE.NLN File not open 

The task attempted to close a file on the physical 
device unit associated with the specified LUN, but 
no file was currently open on that LUN. 

IE. NOD Insufficient buffer space 

Dynamic storage space has been depleted, and there 
was insufficient buffer space available to allocate 
a secondary control block. For example, if a task 
attempts to open a file, buffer space for the 
window and file control block must be supplied by 
the Executive. This code is returned when there is 
not enough space for this operation. 

lE.OFL Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 

lE.OVR Illegal read overlay request 

A read overlay was requested and the physical 
device unit specified in the QIO directive was not 
the physical device unit from which the task was 
installed. The read overlay function can only be 
executed on the physical device unit from which the 
task image containing the overlays was installed. 

lE.PRI Privilege violation 

The task that issued the request was not privileged 
to execute that request. For DECtape, this code is 
returned when a nonprivileged task attempts to read 
or write a mounted volume directly (that is, 
lO.RLB, lO.RLV, lO.WLB, or lO.WLV) . Also, this 
code is returned if any task attempts to attach a 
mounted volume. 

lE.SPC Illegal address space 

The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternately, a byte count of 
was specified. 

(continued on next page) 
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Table 6-3 (Cont.) 
DECtape Status Returns 



Code 


Reason 


lE.VER 


Unrecoverable error 




After the system's standard number of retries has 
been attempted upon encountering an error, the 
operation still could not be completed. For 
DECtape, this code is returned to indicate any of 
the following conditions. 




• A parity error was encountered. 




• The task attempted a forward multiblock transfer 
past block 577 (1101 (8) ) . 




• The task attempted a backward multiblock 
transfer past block 0. 


lE.WLK 


Write-locked device 




The task attempted to write on a DECtape unit that 
was physically write-locked. 



6.4.1 DECtape Recovery Procedures 

When a DECtape I/O error condition is detected, RSX-llM attempts to 
recover from the condition by retrying the function as many as five 
times. Unrecoverable errors are generally parity, mark track, or 
other errors caused by a faulty recording medium or a hardware 
malfunction. An unrecoverable error condition also occurs when a read 
or write operation is performed past the last block of the DECtape on 
a forward operation, or the first block of the DECtape on a reverse 
operation. 



In addition to the standa 
is reported when the " 
number of times the DECta 
while looking for a bloc 
portion of DECtape are 99 
block number 100, maki 
block 100' and the tape is 
searching forward for bio 
96 and, because the drive 
direction and 96 is 1 
Block 101 is the next bio 
100, the driver revers 
search backward. The nex 
the direction is rever 
prevent the DECtape from 
rocking between block 
has been established. 



rd error conditions, an unrecoverable error 
rock count" exceeds 8. The rock count is the 
pe driver reverses the direction of the tape 
k number. Assume that the block numbers on a 
, 96, and 101, where one bit was dropped from 
ng it 96. If an I/O request is received for 
positioned at block 99, the driver starts 
ck 100. The first block to be encountered is 
r is searching for block 100 in a forward 
ess than 100, the search continues forward, 
ck and, because number 101 is greater than 
es the direction of the tape and starts to 
t block number in this direction is 96, and 
sed again because 100 is greater than 96. To 
being hung in this position, continually 
numbers 96 and 100, a maximum rock count of 8 
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6.4.2 Select Recovery 

If the DECtape unit is in an off-line condition when the I/O function 
is performed, the message shown below is output on the operator's 
console. 



*** DTn; 



— SELECT ERROR 



where n is the unit number of the drive that is currently off line. 
The user should respond by placing the unit to REMOTE. The driver 
retries the function, from the beginning, once every second. It 
displays the message once every 15 seconds until the appropriate 
DECtape unit is selected. A select error may also occur when there 
are two drives with the same unit number or when no drive has the 
appropriate unit number. 



6.5 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the DECtape driver described in 
this chapter. 



6.5.1 DECtape Transfers 

If the transfer length on a write is less than 256 words, a partial 
block is transferred with zero fill for the rest of the physical 
block. If the transfer length on a read is less than 256 words, only 
the number of words specified is transferred. If the transfer length 
is greater than 256 words, more than one physical block is 
transferred. 



6.5.2 Reverse Reading and Writing 

The DECtape driver supports reverse reading and writing, because these 
functions speed up data transfers in some cases. A block should 
normally be read in the same direction in which it was written. If a 
block is read from a DECtape into memory in the opposite direction 
from that in which it was written, it is reversed in memory (for 
example, word 255 becomes word 0, and 254 becomes word 1). If this 
occurs, the user must then reverse the data within memory. 



6.5.3 Speed Considerations When Reversing Direction 

It is possible to reverse direction at any time while reading or 
writing DECtape. However, the user should understand that reversing 
direction substantially slows down the movement of the tape. Because 
DECtape must be moving at a certain minimum speed before reading or 
writing can be performed, a tape block cannot be accessed immediately 
after reversing direction. Two blocks must be bypassed before a read 
or write function can be executed, to give the tape unit time to build 
up to normal access speed. Furthermore, when a request is issued to 
read or write in a certain direction, the tape first begins to move in 
that direction, then starts detecting block numbers. The following 
examples illustrate these principles. 
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If a DECtape is positioned at block number 12 and the driver receives 
a request to read block 10 forward, the tape starts to move forward, 
in the direction requested. When block number 14 is encountered, the 
driver reverses the direction of the tape, since 14 is greater than 
10. The search continues backward, and block numbers 11 and 10 are 
encountered. Because the direction must be reversed and the driver 
requires two blocks to build up sufficient speed for reading, block 
number 9 and 8 are also bypassed in the backward direction. Then the 
direction is reversed and the driver encounters blocks 8 and 9 forward 
before reaching block number 10 and executing the read request. 



6.5.4 Aborting a Task 

If a task is aborted while waiting for a unit to be selected, the 
DECtape driver recognizes this fact within 1 second. 
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7.1 INTRODUCTION 

The DECTAPE II (TU58) driver supports TU58 system hardware, providing 
low-cost, block-replaceable mass storage. 



7-1.1 TU58 Hardware 

Each TU58 DECTAPE II system consists of one or two TU58 cartridge 
drives, one tape drive controller, and one DLll-type serial line 
interface. Each TU58 drive functions as a random access, 
block-formatted mass storage device. Each tape cartridge is capable 
of storing 512(10) blocks of 512(10) bytes each. Access time averages 
10 seconds. All I/O transfers (commands and data) occur by means of 
the serial line interface at serial transmission rates of 9600 bps. 
All read and write check operations are performed by the controller 
hardware using a 16-bit checksum. The controller performs up to eight 
attempts to read a block, as necessary, before aborting the read 
operation and returning a hard error; however, whenever more than one 
read attempt is required for a successful read, the driver is notified 
in order to report a soft error message to the error logger. 



7.1.2 TU58 Driver 

The TU58 driver communicates with the TU58 hardware by means of a 
serial line interface (DLll); no other interface is required. All 
data and command transfers between the PDP-11 system and the TU58 are 
done with programmed I/O and interrupt-driven routines; NPRs are not 
supported. 



7.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for the TU58. A bit setting of 1 indicates that the 
described characteristic is true for this device. 
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Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File-structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications channel 

Device mountable as a FILES-11 volume 

Device mountable 

Words 3 and 4 of the buffer are a double-precision number specifying 
the total number of blocks on the device; this value is 512(10) 
blocks. Word 5 indicates the default buffer size, which is 512(10) 
bytes. 



7.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
the TU58. 



7.3.1 Standard QIO Functions 

Table 7-1 lists the standard QIO system directive functions of the QIO 
macro that are valid for the TU58. 



Bit 


Setting 








1 





2 





3 


1 


4 





5 





6 


1 


7 


1 


8 





9 





10 





11 





12 





13 





14 


1 


15 


1 
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Table 7-1 
Standard QIO Functions for the TU58 



Format 


Function 


QIO$C 


10. ATT,... 




Attach device 


QIO$C 


lO.DET,... 




Detach device 


QIO$C 


lO.KIL,... 




Cancel I/O requestsl 


QIO$C 


lO.RLB, . . . ,<stadd,size. 


r ,lbn> 


READ logical block 


QIO$C 


lO.WLB, ,<stadd,size. 


p,lbn> 


WRITE logical block 



1. In-progress operations are allowed to complete when lO.KIL 
is received. I/O requests that are queued when lO.KIL is 
received are killed. 



stadd 



size 



Ibn 



The starting address of the data buffer (must be on a word 
boundary) . 



Th^ data buffer size in bytes (must be even and greater than 0) 



The logical block number on the cartridge tape where the data 
transfer starts (must be in the range of 0-777) . 



7.3.2 Device-Specific QIO Functions 

The device-specific QIO system directive functions that are valid for 
the TU58 are shown in Table 7-2. 



Table 7-2 
Device-Specific QIO Functions for the TU58 



Format 



QIO$C lO.WLC, . .. ,< Stadd, size, ,,,lbn> 
QIO$C lO.RLC, . ..,<stadd,size, , ,,lbn> 
QIO$C lO.BLSlIQ.UMD,. ..,<lbn> 
QIO$C lO.DGN! IQ.UMD- . . . 



Function 



WRITE logical block with check 
READ logical block with check 
POSITION tape 



'Dii>^ •T>-»-l-&»'>-»pT A ^ 
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stadd 



size 



Ibn 



The starting address of the data buffer (must be on a word 
boundary) . 



The data buffer size in bytes (must be even and greater than 0) 



The logical block number on the cartridge tape where the data 
transfer starts (must be in the range of 0-777). 

Additional details for device-specific QIO functions are provided in 
the following paragraphs. 



7.3.2.1 lO.WLC - The lO.WLC function writes the specified data onto 
the tape cartridge. A checksum verification is then performed by 
reading the data just written; data is not returned to the task 
issuing the function. An appropriate status, based on the checksum 
verification, is returned to the issuing task. 



7.3.2.2 lO.RLC - The lO.RLC function reads the tape with an increased 
threshold in the TU58's data recovery circuit. This is done as a 
check to insure data read reliability. 



7.3.2.3 lO.BLS - The lO.BLS function is used for diagnostic purposes 
to position the tape to the specified logical block number. If you 
specify lO.BLS, you must use the IQ.UMD subfunction (see Chapter 1). 



7.3.2.4 lO.DGN - The lO.DGN function is used for diagnostic purposes 
to execute the TU58's internal (firmware) diagnostics. Appropriate 
status information is returned to the issuing task by the I/O status 
block. If you specify lO.DGN, you must use the IQ.UMD subfunction 
(see Chapter 1) . 



7.4 STATUS RETURNS 

Table 7-3 lists the error and status conditions that are returned by 
the TU58 driver. 
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Table 7-3 
TU58 Driver Status Returns 



Code 


Reason 


IS. sue 


Successful completion 




The operation specified in the QIO directive was 




completed successfully. The second word of the I/O 




status block can be examined to determine the number of 




bytes processed, if the operation involved reading or 




writing . 


lE.DNR 


Device not ready 




The physical device unit specified in the QIO directive 




was not ready to perform the desired I/O operation. 


lE.IFC 


Illegal function 




A function code was specified in an I/O request that is 




illegal for the TU58. 


lE.FHE 


Fatal hardware error 


lE.TMO 


Time-out error 




The TU58 failed to respond to a function within the 




normal time specified by the driver. 


lE.VER 


Unrecoverable error 




After the system's standard number of retries (8) has 




been attempted upon encountering an error, the operation 




still could not be successfully completed. 


lE.WLK 


Cartridge write-locked 




The task attempted to write on a tape cartridge that is 




physically write-locked. 
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MAGNETIC TAPE DRIVERS 



8.1 INTRODUCTION 

RSX-llM and RSX-llM-PLUS support a variety of magnetic tape devices. 
Table 8-1 summarizes these devices and subsequent sections describe 
them in greater detail. 

Programming for magtape is quite similar to programming for the 
magnetic tape cassette (see Chapter 9) . Unlike cassette, however, 
magtape can handle variable-length records and allows the user to 
select a parity mode. 



8.1.1 TE10/TD10/TS03 Magnetic Tape 

The TE10/TO10/TS03 consists of a TMll controller with a TEIO, TUlO, or 
TS03 transport. It is a low-cost, high-performance system for serial 
storage of large volumes of data and programs in an 
industry-compatible format. All recording is nonreturn-to-zero, 
inverted (NRZI) . 



8.1.2 TE16/TD16/TU45/TD77/TD78 Magnetic Tape 

The TE16/TU16/TU45/TU77/TU78 consists of an RH11/RH70 controller, a 
TM02, TM03, or TM78 formatter, and a TE16/TU16/TU45/TU77/TU78 
transport. They are quite similar to the TEIO/TUIO but are Massbus 
devices, with a common controller, a specialized formatter, and 
drives. Recording is either 800 bpi NRZI or 1600 bpi phase-encoded 
(PE) for the TE16/TU16/TU45/TU77. The TU78 records in 1600 bpi 
phase-encoded or 6250 bpi GCR modes. 



8.1.3 TS11/TD80 Magnetic Tape 

The TSll and TU80 are integrated subsystems. Each has a drive, a 
controller, and a formatter. The hardware is microprocessor 
controlled for all operations, including I/O transfers, tape motion, 
and so forth, and has comprehensive (internal) diagnostic test 
execution. Recording is 1600 bpi phase-encoded (PE) . 

The TSll operates in conventional start and stop mode while the TU80 
operates at either low speed (start and stop mode) or high speed 
(streaming mode) . Tape speed is microprocessor controlled. 
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8.1.4 TSV05 Magnetic Tape 

The TSV05 tape subsystem is a Q BUS device. It is an integrated 
subsystem with a drive, a controller, and a formatter. The hardware 
is microprocessor controlled for all operations, including I/O 
transfers, tape motion, and so forth and has comprehensive (internal) 
diagnostic test execution. Recording is 1500 bpi phase-encoded (PE) . 
The TSV05 operates at 25 inches per second. 



Table 8-1 
Standard Magtape Devices 



Devices 


Channels 


Recording Density 
(Frames/Inch) 


Tape Speed 
(Inches/Second) 


Maximum Data 
Transfer Rate 
(Bytes/Second) 


Recording 
Method 


TE10,T010 


9 (TEIO) 
7 or 9 (TOIO) 


For 7-ohannel: 

200, 556, or 

800 

For 9-channel: 

800 


45 


36,000 


NRZI 


TE16,.T016 


9 


800 or 1600 


45 


For 800 bpi : 

36,000 

For 1600 bpi: 

72,000 


NRZI or 

Phase 

Encoding 


T045 


9 


800 or 1600 


75 


For 800 bpi: 

60,000 

For 1600 bpi: 

120,000 


NRZI or 

Phase 

Encoding 


T077 


9 


800 or 1600 


125 


For 800 bpi: 

100,000 

For 1600 bpi: 

200,000 


NRZI or 

phase 

Encoding 


TS03 


9 


800 


15 


12,000 


NRZI 


TSll 


9 


1600 


45 


72,000 


Phase Encoding 


TU78 


9 


1600 or 6250 


125 


For 1600 bpi: 

200,000 

For 6250 bpi: 

781,000 


Phase Encoding 
or GCR (Group 
Cyclical 
Recording) 


TO80 


9 


1600 


25l 
lOO'' 


40,000l 
160, 000^ 


Phase Encoding 


TSV05 


9 


1600 


25 


40,000 


Phase Encoding 



1. Low Speed 

2. High Speed 
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8.2 GET LDN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for magtapes. A bit setting of 1 indicates that the 
described characteristic is true for magtapes. 

Meaning 

Record-oriented device (0 if the tape is 
mounted, 1 if it is not) 

Carriage-control device 

Terminal device 

File-structured device 

Single-directory device (0 if the tape is not 
mounted, 1 if it is) 

Sequential device 

Mass storage device 

User-mode diagnostics supported-*- 

Massbus device (set only for TE16, TU16 , 
TU45, TU77, or TU78 drives interfaced by 
means of an RH70 controller)! 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications 
channel 

Device mountable as a FILES-11 volume^ 

Device mountable^ 

Words 3 and 4 of the buffer are undefined; word 5 indicates the 
default buffer size, for magtapes 512 bytes. 



8.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
the magtape drivers. 



Bit 


Setting 





or 1 


1 





2 





3 





4 


or 1 


5 


1 


6 


1 


7 


or 1 


8 


or 1 



9 





10 





11 





12 





13 





14 


or 1 


15 


or 1 



1. SYSGEN and device-dependent characteristic. 
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8.3.1 Standard QIO Functions 

Table 8-2 lists the standard functions of the QIO macro that are valid 
for magtape. 



Table 8-2 
Standard QIO Functions for Magtape 



Format 


Function 


QIO$C 10. ATT,... 
QI0$C lO.DET,... 
QIO$C lO.KIL,... 
QIO$C lO.RLB, ,<stadd,size> 

QIO$C lO.RVB, . . .,<stadd,size> 

QIO$C lO.WLB, .. . ,<stadd,size> 

QIO$C lO.WVB,.. .,<stadd,size> 


Attach device 

Detach device 

Cancel I/O requests 

READ logical block 
(read tape into buffer) 

READ virtual block 
(read tape into buffer) 

WRITE logical block 

(write buffer contents to tape) 

WRITE virtual block 
(write buffer contents to tape) 



stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



size 

The data buffer size in bytes. Size must be even, greater than 
0, and, for a write, must be at least 14 bytes. 

lO.KIL does not cancel an in progress request unless a select error 
has occurred . 



8.3.2 Device-Specific QIO Functions 

Table 8-3 lists the device-specific functions of the QIO macro that 
are valid for magtape. Additional details on certain functions appear 
below. 



8.3.2.1 lO.RLV - The data appears in the specified buffer in a 
fashion identical with lO.RLB or lO.RVB, as long as the data block has 
the same length as the buffer. 
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8.3.2.2 lO.RWD - Completion of lO.RWD means that the rewind has been 
initiated. Additional operations on that controller may then be 
queued. However, a request for the same unit will be queued by the 
driver until load point (BOT) is reached. 



8.3.2.3 lO.RWU - lO.RWU is normally used when operator intervention 
is required (for example, to load a new tape) . The operator must turn 
the unit back on line manually before subsequent operations can 
proceed. 



Table 8-3 
Device-Specific QIO Functions for Magtape 



Format 



QIO$C lO.DSE,... 
QIO$C 10. EOF,... 
QIO$C lO.ERS,... 

QIO$C lO.RLV,. .. ,<stadd,size> 



QIO$C 


lO.RWD,. .. 


QIO$C 


lO.RWU,. .. 


QIO$C 


10. SEC,... 


QIO$C 


I0.SMO,...,<cb> 


QIO$C 


lO.SPB, ,<nbs> 


QIO$C 


lO.SPF, . . , ,<nes> 


QIO$C 


lO.STC,. .. ,<cb> 



Function 



Data Security Erase (TU78 only) 



Write end-of-file mark (tape mark) 



Erase (TEIO and TUlO not 
supported) 



READ logical block reverse (TEIO 
and TUlO not supported.) 



Rewind unit 



Rewind and turn unit off line 



Sense tape characteristics 



MOUNT tape and set tape 
characteristics (Unit must be 
READY, tape at LOAD POINT.) 

SPACE blocks 



SPACE files 



SET tape characteristics 



cb 



nbs 



The characteristic bits to set, 



The number of blocks to space past (positive if forward, 
negative if reverse) , 
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The number of EOF marks to space past (positive if forward, 
negative if reverse) . 



size 



The size of the stadd data buffer in bytes (must be an even 
number of bytes greater than 0) . 



stadd 



The starting address of the data buffer (may be on a byte 
boundary) . 



8.3.2.4 lO.ERS - Erases 3 inches of (write blank) tape, effectively 
providing an extended interrecord gap. (Not supported on TUlO and 
TEIO.) 



8.3.2.5 lO.DSE - The TU78 will erase from the current position to 
end-of-tape and then rewind the tape to beginning-of-tape. 



8.3.2.6 10. SEC - This function returns the tape characteristics in 
the second I/O status word. The tape characteristic bits are defined 
as follows: 



Bit 



Meaning When Set 



Can Be Set by 
lO.SMO and lO.STC 



For TUlO, 556 bpi 
density (7-channel) . 
For TE16, TU16, TU45, TU77, 
TU78, and TSll, reserved. 

For TUlO, 200 bpi 

density (7-channel) . 

For TE16, TU16, TU45, TU77, and 

TU78, reserved. 

For TSll, TU80, and TSV05, 
swap byte mode (read/write) . 

For TUlO, core-dump 
mode (7-channel, see below). 
For TE16, TU16, TSll, TU45, 
TU77, and TU78 reserved. 

Even parity (default is odd) . 
(Not selectable for the TSll.) 

Tape is past EOT. 

Last tape command encountered 
EOF (unless last command was 
backspace) . 
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Can Be Set by 
Bit Meaning When Set lO.SMO and lO.STC 

6 Writing is prohibited. X 

7 Writing vjith extended inter- X 
record gap is prohibited 

(that is, no recovery is attempted 
after write error) . 

8 Select error on unit. 

9 Unit is rewinding. 

10 Tape is physically write-locked . 

11 For TEIO, TUlO, and TS03, reserved. X 
For all other tapes, 1600 bpi density. 

12 For TUlO, drive is 7-channel. 
For all other tapes, reserved. 

13 Tape is at load point (EOT) . 

14 Tape is at end-of-volume (EOV) . 

15 Tape is past EOV (reserved for dri- 
ver; always when read by user). 

In core-dump mode (TUlO only, 800 bpi density, and 7-channel) , each 
8-bit byte is written on 2 tape frames, 4 bits per frame. In other 
modes on 7-channel tape, only 6 low-order bits per byte are written. 

For the TSll, 1600 bpi density is always selected (bit 11=1) . Bit 11 
cannot be modified by either the lO.SMO or lO.STC functions. For 
drives that use the TM03 controller, this bit can be either set or 
cleared; however, once the tape is moved from the load (beginning of 
tape) position (EOT) , the device driver modifies this bit to reflect 
the actual density of the tape currently mounted. You cannot change 
bit 11 once the tape is moved beyond EOT. For the TU78, bit 11 set 
indicates 1600 bpi and bit 11 clear indicates 6250 bpi. Bit 11 cannot 
be set or cleared once the tape is moved beyond BOT. 

The effect of these settings is illustrated in Figure 8-1 for the TEIO 
and TUlO, and in Figure 8-2 for the TE16, TU16, TU45, and TU77. 
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SET EVEN 
PARITY 



YES 



EVEN 
PARITY 

9 



SET 800 BPI, 
NINE-CHANNEL 



YES 



NINE- 
CHANNEL 
TAPE 



CORE 
DUMP 
MODE 



YES 



SET 800 BPI, 

SEVEN-CHANNEL, 

CORE-DUMP 

MODE 



SET 556 BPI, 
SEVEN-CHANNEL 



YES 



556 BPI 
7 




YES 



SET 200 BPI, 
SEVEN-CHANNEL 



SET 800 BPI, 
SEVEN-CHANNEL 



I END I 



Figure 8-1 Determination of Tape Characteristics for the TEIO/TUIO 
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SET 1600 BPI 



YES 




SET 800 BPI 




YES 



SET 
EVEN PARITY 



Figure 8-2 Determination of Tape Characteristics 
for the TE16/TU16/TU45/TU77 



8.3.2.7 lO.SMO - This function can be used as a combination of the 
sense (10. SEC) and set (lO.STC) tape characteristics functions. 
Unlike lO.STC, however, the lO.SMO function requires that the unit be 
READY and the tape be at load point (BOT) . If either of these 
conditions is not met, the function returns an error status code of 
lE.FHE (refer to Table 8-4). 

The lO.SMO function should be used to set the characteristics of a 
newly loaded tape. If the lE.FHE error code is returned, the tape 
drive is not on line and is not at BOT. 
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8.4 STATUS RETURNS 

The error and status conditions listed in Table 8-4 are returned by 
the magtape drivers described in this chapter. 



Table 8-4 
Magtape Status Returns 



Code 


1 

Reason 


IS. sue 


Successful completion 




The operation specified in the QIO directive was 




completed successfully. The second word of the I/O 




status block can be examined to determine the 




number of bytes processed, if the operation 




involved reading or writing. This code is also 




returned if nbs equals in an lO.SPB function or 




if nes equals in an lO.SPF function. 


IS.PND 


I/O request pending 




The operation specified in the QIO directive has 




not yet been completed. The I/O status block is 




filled with Os. 


IE. ABO 


Operation aborted 




The specified I/O operation was canceled by lO.KIL 




while in progress or while still in the I/O queue. 


lE.BBE 


Bad block 




A bad block was encountered while reading or 




writing and the error persists after nine retries. 




The number of bytes transferred is returned in the 




second word of the I/O status block. For TMll, 




lE.BBE may also indicate that a bad tape error 




(BTE) has been encountered while reading or 




spacing . 


IE. BYT 


Byte-aligned buffer specified 




Byte alignment was specified for a buffer, while 




only word alignment is legal for the QIO. 




Alternatively, the length of a buffer is not an 




even number of bytes. 


lE.DAA 


Device already attached 




The physical device unit specified in an 10. ATT 




function was already attached by the issuing task. 




This code indicates that the issuing task has 




already attached the desired physical device unit. 




not that the unit was attached by another task. 



(continued on next page) 
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Table 8-4 (Cont.) 
Magtape Status Returns 



Code 



Reason 



lE.DAO Data overrun 

On a read, a record exceeded the stated buffer 
size. The final portion of the buffer is checked 
for parity, but is not read into memory. 

lE.DNA Device not attached 

The physical device unit specified in an lO.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks, 

lE.DNR Device not ready 

The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. This code is returned to indicate one 
of the following conditions: 

• A time-out occurred on the physical device unit 
(that is, an interrupt was lost). 

• A vacuum failure occurred on the magtape drive. 

• While trying to read or space, the driver 
detected blank tape. 

• The LOAD switch on the physical drive was 
switched to the off position. 

• The unit failed internal diagnostic tests {TS04 
only) 

IE. EOF End-of-file encountered 

An end-of-file (tapemark) was encountered. 

IE. EOT End-of-tape encountered 

The end-of-tape (physical end-of-volume) was 
encountered while the tape was moving in the 
forward direction. A 10-foot length of tape is 
provided past EOT to be used for writing data and 
markers, such as volume trailer labels. The IE. EOT 
code will continue to be returned in the I/O status 
block until the EOT marker is passed in the reverse 
direction. IE. EOT is not returned on a read 
operation. 

(continued on next page) 
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Table 8-4 (Cont.) 
Magtape Status Returns 



Code 



Reason 



lE.EOV 



lE.FHE 



End-of -volume encountered (unlabeled tape) 

On a forward space function, the logical 
end-of-volume was encountered. An end-of-volume is 
two consecutive end-of-file marks (EOF) , or a 
beginning-of-tape mark (BOT) followed by an EOF. 
The tape is normally left positioned between the 
two marks. 

Fatal hardware error 

Nonrecoverable hardware malfunction: e.g., magtape 
unit not READY and/or tape not at LOAD POINT when 
lO.SMO is issued. 



lE.IFC 



lE.OFL 



lE.SPC 



lE.VER 



lE.WLK 



Illegal function 

An illegal function (or subfunction bit) was 
specified in a magtape I/O request. Refer also to 
Section 8.4.3. 

Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 

Illegal address space 

The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. For magtape, this code is 
also returned if a byte count of was specified or 
if the user attempted to write a block that was 
less than 14 bytes long. 

Unrecoverable error 

After the system's standard number of retries has 
been attempted upon encountering an error, the 
operation still could not be completed. For 
magtape, this code is returned in the case of CRC 
or checksum errors or when a tape block could not 
be read . 

Write-locked device 

The task attempted to write on a magtape unit that 
was physically write-locked. Alternatively, tape 
characteristic bit 6 was set by the software to 
write-lock the unit logically. 
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After processing a QIO request, the magnetic tape driver returns two 
status words. The first word contains one of the I/O status codes 
listed in Table 8-4. 

For successful QIO execution (IS.SUC) or read requests (lE.DAO) , the 

second I/O status word may contain further information. The 

operations for which this is true, and the information returned, are 
shown in Table 8-5. For all other cases this word is undefined. 



Table 8-5 
Information Contained in the Second I/O Status Word 



I/O Function Code 


Information Returned 


lO.RLB 
lO.RLV 
lO.RVB 
10. SEC 
lO.SPB 
lO.SPP 
lO.WLB 
lO.WVB 


Number of bytes transferred 
Number of bytes transferred 
Number of bytes transferred 
Tape characteristics word 
Number of records spaced over 
Number of files spaced over 
Number of bytes transferred 
Number of bytes transferred 



8.4.1 Select Recovery 

If a request fails because the desired unit is off line, no drive has 
the desired unit number, or has its power off, the following message 
is output on the operator's console: 

*** MTn: — SELECT ERROR 



The unit number of the specified drive. 

The driver checks the unit for readiness and repeats the message every 
15 seconds until the requesting task is aborted or the unit is made 
available. In the latter case, the driver then proceeds with the 
request. 



8.4.2 Retry Procedures for Reads and Writes 

If an error occurs during a read (for example, vertical parity error), 
the recovery procedure depends on the type of magtape in use. Read 
errors for TEIO, TUlO, TS03, TE16, TU16, TU45, TU77, are retried by 
backspacing one record and then rereading the record in question. If 
the error persists after nine retries, lE.VER is returned. Read 
errors for the TU78 are retried using a combination of backspacing one 
record and then rereading the record in question, rereading in the 
opposite direction, rereading at both normal/low thresholds, and 
Cieaning tue tape. 
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Read errors for the TSll, TU80, and TSV05 are retired by rereading the 
block in error a predetermined number of times. Every eighth reread, 
the block is passed by the tape cleaner blade. If the error persists 
after a predetermined number of retries, lE.VER is returned. 

Write recovery is the same for all devices. When a write operation 
fails, the driver attempts the following error recovery procedure: 

1. Repositions the tape 

2. Erases three inches of tape (resulting in an extended 
interrecord gap) 

3. Retries the write operation 

If the error persists after a predetermined number of retries, lE.VER 

is returned. The requesting task can use lO.STC to prohibit writing 

with an extended interrecord gap. In this case, the tape is 
backspaced and the write is retried. 



8.4.3 Power-Fail Recovery for Magnetic Tapes 

If a power failure and/or loss of vacuum occurs on a magnetic tape 
drive, tape position is lost- (Note that an initial system boot 
simulates a recovery from a power failure.) Additionally, on auto-load 
drives, the tape will be positioned at BOT when the unit is turned on 
line . 



To prevent 
driver ma 
is set, th 
until a 
characteri 
the power 
It is also 
functions 
These func 



accidental des 
intains a powe 
e driver disall 
rewind (lO.RWD 
sties (lO.SMO) 
-fail indicate 
possible to 

(lO.STC and I 
tions, however. 



truction of data currently on tape, the 
r-fail status indicator. When this indicator 
ows any data transfer or tape motion commands 
), rewind unload (lO.RWU), or mount and set 
function is issued. These functions clear 
r and allow all tape functions to be issued. 

issue the set and sense characteristics 
O.SEC) while the power-fail indicator is set. 

will not clear the bit. 



All functions other than those just described are considered illegal 
and cause the return of the lE.IFC (illegal function) error code to 
the requesting task. In situations where a tape is currently a 
mounted volume, the tape should be dismounted and then remounted 
before use. In doing this, the rewind command will be issued, thereby 
clearing the power-fail indicator. 



8.5 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of magtape drivers described in this 
chapter . 



8.5.1 Block Size 

Each block must contain an even number of bytes, at least 14 for a 
write and at most 65,534. However, tape usage is more efficient with 
a larger buffer. 
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8.5.2 ImportaDce of Resetting Tape Characteristics 

A task that uses magtape should always set the tape characteristics to 
the proper value before beginning I/O operations. The task cannot be 
certain in what state a previous task left these characteristics. It 
is also possible that an operator might have changed the magtape unit 
selection. If the selection switch is changed, the new physical 
device unit may not correspond to the characteristics of the unit 
described by the respective unit control block. 



8.5.3 Aborting a Task 

If a task is aborted while waiting for a magtape unit to be selected , 
the magtape driver recognizes this fact within 1 second. 

If a task is aborted while waiting for a magtape unit to complete a 
space operation, the magtape driver may allow spacing to the next tape 
mark. 



8.5.4 Writing an Even-Parity Zero-NRZI 

If an even-parity were written normally, it would appear to the 
drive as blank tape. It is therefore converted to 20 (8). If this 
conversion is undesirable, the user must ensure that no even-parity Os 
are output on the tape. 



8.5.5 Density Selection 

The TM03 and TM78 controllers impose the following density selection 
restriction: The user cannot mix recording densities on any volume 
associated with the controller. 

Density for write operations is selected when the tape is at the load 
(BOT) position. Density for read operations is hardware - selected 
during the first read (away from BOT); after the first read, the 
10. SEC function can be used to determine (sense) tape density. 



8.5.6 End-of-Volume Status (Unlabeled Tape) 

The magnetic tape driver detects end-of-volume when it spaces over the 
second of two consecutive tape marks. The tape is left positioned 
between the two tape marks. 

The magnetic tape driver returns the lE.EOV status code only on space 
operations. lE.EOV is never returned by read operations. 

For the purpose of checking for end-of-volume, the driver treats 
beginning of tape (BOT) as a tape mark. Therefore, any forward space 
operation from BOT that immediately encounters a tape mark will return 
lE.EOV. 

■»■■»- a space opera *, ion Si^ops between two tape marKS uut <joes not space 
over the second one, the driver will return end of file rather than 
end-of-volume. Any subsequent space operation from this point that 
Immediately spaces over the second tape mark will return 
end-of-volume. 
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During lO.SPF operations, the driver considers all tape marks to be 
files except for BOT and for the second tape mark spaced over at the 
end of volume. 

Note that both lO.SPF and lO.SPB operations leave the tape positioned 
after the tape mark in the direction of travel. 

If you want to treat two consecutive tape marks as end-of-volume on 
read operations, your application must keep track of the tape marks. 
The magnetic tape driver does not support two consecutive tape marks 
as end-of-volume on read operations. 



8.5.7 Resetting VCK Indicator 

When the tape transport status for a TSll, TU80, or TSV05 changes 
(goes on-line or off-line) , further I/O operations are inhibited. A 
deliberate I/O sequencing must occur to reset the VCK indicator and 
allow physical I/O to proceed. This sequencing is done by issuing a 
lO.RWD or lO.SMO QIO or including /RW or /REW switches to command 
requests (such as DMP) . 
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CHAPTER 9 
CASSETTE DRIVER 



9.1 INTRODUCTION 

RSX-llM supports the TAll magnetic tape cassette (a TAll controller 
with a TU60 dual transport) . Programming for cassette is quite 
similar to programming for magtape (see Chapter 8) . The TAll system 
is a dual-drive, reel-to-reel unit designed to replace paper tape. 
Its two drives run nonsimultaneously, using DIGITAL Proprietary 
Philips-type cassettes. 

The maximum capacity of a cassette, in bytes, is 92,000 (minus 300 per 
file gap and 45 per interrecord gap) . It can transfer data at speeds 
of up to 562 bytes per second. Recording density ranges from 350 to 
700 bits ber inch, depending on tape postion. 



9.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for cassettes. A bit setting of 1 indicates that the 
described characteristic is true for cassettes. 

Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 



Bit 


Setting 





1 


1 





2 





3 





4 





5 


1 


6 


1 


7 





8 
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Meaning 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications channel 

Device mountable as a FILES-11 volume 

Device mountable 

Words 3 and 4 of the buffer are undefined; word 5 indicates the 
default buffer size, for cassettes 128 bytes. 



it 


Setting 


9 





10 





11 





12 





13 





14 





15 






9.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
the cassette driver. 



9.3.1 Standard QIO Functions 

Table 9-1 lists the standard functions of the QIO macro that are valid 
for cassette. 



Table 9-1 
Standard QIO Functions for Cassette 



Format 


Function 


QIO$C 


lO.ATT,... 


Attach device 


QIO$C 


lO.DET,. . . 


Detach device 


QIO$C 


lO.KIL,... 


Cancel I/O requests 


QIO$C 


lO.RLB, . . . ,<stadd,size> 


READ logical block 
(read tape into buffer) 


QIO$C 


lO.RVB, . . . ,<stadd,size> 


READ virtual block 
(read tape into buffer) 


QIO$C 


lO.WLB, . .. ,<stadd,size> 


WRITE logical block 
(write buffer contents to 
tape) 


QIO$C 


lO.WVB, . . . ,<stadd,size> 


WRITE virtual block 
(write buffer contents to 
tape) 
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stadd 



The starting address of the data buffer (may be on a byte 
boundary) . 



size 



The data buffer size in bytes (must be greater than 0) 



lO.KIL does not affect in-progress requests. 



9.3.2 Device-Specific QIO Functions 

Table 9-2 lists the device-specific functions of the QIO macro that 
are valid for cassette. The section on programming hints below 
provides more detailed information about certain functions. 



9.4 STATUS RETURNS 

The error and status conditions listed in Table 9-3 are returned by 
the cassette driver described in this chapter. 



Table 9-2 
Device-Specific QIO Functions for Cassette 



Format 


Function 


QIO$C 


10. EOF,.. . 




Write end-of-file 


gap 


QIO$C 


lO.RWD,. . . 




Rewind unit 




QIO$C 


lO.SPB,.. . 


,<nbs> 


SPACE blocks 




QIO$C 


lO.SPF,... 


,<nes> 


SPACE files 





nbs 



nes 



The number of blocks to space past (positive if forward, negative 
if reverse) . 



The number of EOF gaps to space past (positive if forward, 
negative if reverse) . 
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Table 9-3 
Cassette Status Returns 



Code 


Reason 


IS. sue 


Successful completion 




The operation specified in the QIO directive was 
completed successfully. The second word of the I/O 
status block can be examined to determine the 
number of bytes processed if the operation involved 
reading or writing, or, the number of blocks or 
files spaced if the operation involved spacing 
blocks or files. 


IS.PND 


I/O request pending 




The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 


IE. ABO 


Operation aborted 




The specified I/O operation was canceled by lO.KIL 
while still in the I/O queue. 


lE.DAA 


Device already attached 




The physical device unit specified in an 10. ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. 


lE.DAO 


Data overrun 




The driver was not able to sustain the data rate 
required by the TAll controller. 


lE.DNA 


Device not attached 




The physical device unit specified by an lO.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks. 


lE.DNR 


Device not ready 




The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. This code is returned to indicate one 
of the following conditions: 




• The cassette has not been physically inserted. 




• The unit is off line. 




• A time-out occurred on the physical device unit 
(that is, an interrupt was lost). 



(continued on next page) 
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Table 9-3 (Cont.) 
Cassette Status Returns 



Code 



Reason 



IE. EOF 



End-of-file encountered 



IE . EOT 



An end-of-file gap was recognized on the cassette 
tape. This code is returned if an EOF gap is 
encountered during a read, or if the cassette is 
physically removed during an I/O operation. 

End-of-tape encountered 

While reading or writing, clear trailer at 
end-of-tape (EOT) was encountered. Unlike magtape, 
writing beyond EOT is not permitted on cassettes. 
This condition is always sensed on a write before 
it would be sensed on a read of the same section of 
tape. If IE. EOT is returned during a write, the 
cassette head has encountered EOT before finishing 
the writing of the last block. It is recommended 
that the user entirely rewrite the block on another 
cassette. 



IE. IPC 



lE.OFL 



Illegal function 

A function code was specified in an I/O request 
that is illegal for cassette. 

Device off line 



lE.SPC 



lE.VER 



The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not in 
the configuration. 

Illegal address space 

The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternatively, a byte count 
of was specified on a transfer. 

Nonrecoverable error 



This code is 
occurs (see 
check (CRC) , 
each block, 
read operat 
correctly, 
not specify 
the record 
returned, th 
backward one 



returned wh 

Section 9.6. 

a 2-byte val 
is a checksum 
ions to ens 

This is retu 
exactly the n 

on tape. If 
e user may at 

block and re 



en a block check error 
5) . The cyclic redundancy 
ue located at the end of 

that is tested during all 
ure that data is read 
rned if a read request did 
umber of bytes of data in 

a nonrecoverable error is 
tempt recovery by spacing 
trying the read operation. 



lE.WLK 



Write-locked device 



The task attempted to write on a cassette unit that 
was physically write-locked. This code may be 
returned after an lO.WLB, lO.WVB, or 10. EOF 
function. 
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9.4.1 Cassette Recovery Procedures 

If an error occurs during a read or write operation, the operation 
should be retried several times. The recommended maximum number of 
retries is nine for a read and three for a write because each retry 
involves backspacing, which does not always position the tape in the 
same place. More than three retries of a write operation may destroy 
previously written data. For example, to retry a write, it is best to 
space two blocks in reverse, then space one block forward. This 
insures the tape is in the proper position to rewrite the block that 
encountered the error. 

After read and write functions, the second I/O status word contains 
the number of bytes actually processed by the function. After spacing 
functions, it contains the number of blocks or files actually spaced. 



9.5 STRUCTURE OF CASSETTE TAPE 

Figure 9-1 illustrates a general structure for cassette tape. A 
different structure can be employed if the user wishes. 

Here the tape consists of blocks of data interspersed with sections of 
clear tape that serve as leader, trailer, interrecord gaps (IRGs) , and 
end-of-file gaps. 

The logical end-of-tape in this case consists of a sentinel label 
record, rather than the conventional group of end-of-file gaps. Each 
file must contain at least one block. The size of each block depends 
upon the number of bytes the user specifies when writing the block. 

IRGS 




150 FEET 



Figure 9-1 Structure of Cassette Tape 



Abbreviation 

CL 

BOT 

LPG 

LR 

REC 



Meaning 

Clear leader 

Physical beginning-of-tape 

Load point gap (blank tape written by driver 
before the first retrievable record) 

File label record 

Fixed-length record (data) 
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Abbreviation 
EOF 

IRG 

SLR 

LEOT 

EOT 

CT 



Meaning 



End-of-file gap 
Interrecord gap 
Sentinel label record 
Logical end-of-tape 
Physical end-of-tape 
Clear trailer 



9.6 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the cassette driver described in 
this chapter. 



9.6.1 Importance of Rewinding 

The first cassette operation performed on a tape must always be a 
rewind to ensure that the tape is positioned to a known place. When 
it is positioned in clear tape, there is no way to determine whether 
it is in leader at the beginning-of-tape (BOT) or in trailer at the 
end-of-tape (EOT) . 



9.6.2 End-of-File and lO.SPF 



The har 

issued 

positio 

gap. 

lO.SPF 

is pos 

file ga 
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read or 

lO.SPB 

block. 
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a time-out 
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direction 
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the way from 
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is all th 
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the reverse direction 


(nes 


is n 


-third 


of the wa 


y from the beg 


two-th 


irds of the 
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from 


the 


Th 
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correctly 


posi 


issui 


ng lO.SPF in 


reverse. 


the 


r one 


block, foil 


owed 


by lO.SPB 



. When lO.SPF is 
tive) , the tape is 

of the final file 
the file gap. When 
egative) , the tape 
inning of the final 

beginning of the 
tion the tape for a 
user should issue 

in reverse for one 



9.6.3 The Space Functions, lO.SPB and lO.SPF 

lO.SPB always stops in an IRG gap, lO.SPF in an EOF gap. Neither 
space function actually takes effect until data is encountered. For 
example, suppose the tape is positioned in clear leader at BOT and the 
user requests that one block be spaced forward. The drive passes over 
the remaining leader until it reaches data, passes one block, and 
stops in the IRG. Similarly, if the same command is issued when the 
tape is at BOT on a blank tape or a tape containing only EOF gaps, the 
function does not terminate until EOT. 
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9.6.4 Verifying of Write Operations 

Certain errors, such as cyclic redundancy check, are detected on read 
but not write operations. Therefore, to ensure reliability of 
recording, it is recommended that the user perform a read in order to 
verify every write operation. 



9.6.5 Block Length 

The user must specify the exact number of bytes per block when 
requesting read or write operations. An attempt to read a block with 
an incorrect byte count causes an unrecoverable error (see Section 
9.4) to occur. 



9.6.6 Logical End-of-Tape 

The conventional method of signaling logical end-of-tape by multiple 
EOF gaps is inadequate for cassettes, because multiple EOF gaps are 
not distinguishable from each other. For example, two sequential EOF 
gaps would be read as three instead of two. Also spacing functions, 
since they are triggered by encountering data, can not recognize 
multiple EOF gaps. Consequently, the use of a sentinel or key record 
to signal logical end-of-tape is recommended. 
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LINE PRINTER DRIVER 



10.1 INTRODDCTION 

The RSX-llM line printer driver supports the line printers summarized 
in Table 10-1. Subsequent sections of this chaoter describe <-Vios- 
printers in greater detail. 

Table 10-1 
Standard Line Printer Devices 



Controller 


Printer 


Column Width 


Character Set 


Lines per Minute 


LPll-C 


LP14-C 


132 


64 


890 


LPll-D 


LP14-D 


132 


96 


650 


LPll-F 


LPOl-F 


80 


64 


170-1110 


LPll-H 


LPOl-H 


80 


96 


170-1110 


LPll-J 


LP02-J 


132 


64 


170-1110 


LPll-K 


LP02-K 


132 


96 


170-1110 


LPll-R 


LP04-R 


132 


64 


1110 


LPll-S 


LP04-S 


132 


96 


1110 


LPll-V 


LP05-V 


132 


64 


300 


LPll-W 


LP05-W 


132 


96 


300 


LPll-Y 


LP06-Y 


132 


64 


600 


LPll-Z 


LP06-Z 


132 


96 


460 


LPll-GA 


LP07 


132 


96 


1200 


LPll-EA 


LP26 


132 


64 


600 


LPll-EB 


LP26 


132 


64/96 


600/420 


LPll-UA 


LP27 


132 


64/96 


1200/800 


LSll 


LSll 


132 


62 


60-200 


LVll 


LVOl 


132 


96 


500 


LAI 80 


LA180 


132 


96 


150 


LNOl 


LNOl 


Variable 


* 


600 


* Software 


selectab: 


Le fonts not sv 


apported by RSX 
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10.1.1 LPll Line Printer 

The LPll is a high-speed line printer available in a variety of 
models. The LPll model line consists of band line printers and drum 
line printers. The drum printers are impact printers, that use one 
hammer per column and a revolving drum with uppercase and optional 
lowercase characters. The LPll-R and LPll-S are fully buffered models 
that operate at a standard speed of 1110 lines per minute. The other 
LPll drum models have 20-character print buffers. These printers are 
therefore able to print at full speed if the printed line is no longer 
than 20 characters. Lines that exceed this maximum are printed at a 
slower rate. Forms with up to six parts may be used for multiple 
copies. The band line printers are impact printers that have a flat 
steel belt with raised metal characters on the face. The LP07, LP26, 
and LP27 offer speeds from 420 to 1200 lines per minute. 



10.1.2 LSll Line Printer 

The LSll is a medium-speed line printer. It has a 20-character print 
buffer, and lines of 20 characters or less are printed at a rate of 
200 lines per minute. Longer lines are printed at a slower rate. 
RSX-llM does not support the LSll expanded character set feature. 



10.1.3 LVll Line Printer 

The LVll is a fully-buffered, electrostatic printer-plotter that 
operates at a standard rate of 500 lines per minute. RSX-llM supports 
only the LVll print capability, not the plotter mode. 



10.1.4 LA180 DECprinter 

The LA180 is a 180-character/sec, dot-matrix impact printer. It 
accepts multipart forms and pages of various lengths and widths. 



10.1.5 LNOl Laser Printer 

The LNOl is a non-impact page printer that uses laser imaging combined 
with xerographic printing. This technology provides letter quality 
printing at line printer speeds with no noise. Printing is done on 
standard 8 1/2 inch by 11 inch paper at 12 pages per minute, which 
equates to 600 lines per minute. Contributing to the high print 
quality is a printer resolution of 300 by 300 dots per inch. The LNOl 
offers the speed of a line printer with the advantages of a 
phototypeset device. 



10.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for line printers. A bit setting of 1 indicates that the 
described characteristic is true for line printers. 
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Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications channel 

Device mountable as a FILES-11 volume 

Device mountable 

Words 3 and 4 of the buffer are undefined; word 5 indicates the 
default size for the device, for line printers the width of the 
printer carriage (that is, 80 or 132). 



Bit 


Setting 





1 


1 


1 


2 





3 





4 





5 





6 





7 





8 





9 





10 





11 





12 





13 





14 





15 
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10.3 QIO MACRO 

Table 10-2 lists the standard functions of the QIO macro that are 
valid for line printers. 



Table 10-2 
Standard QIO Functions for Line Printers 



Format 


Function 


QIO$C 


lO.ATT,. . . 


Attach device 


QIO$C 


lO.DET, .. . 


Detach device 


QIO$C 


lO.KIL,... 


Cancel I/O requests 


QIO$C 


lO.WLB, . . . ,<stadd,size,vfc> 


WRITE logical block 
(print buffer contents) 


QIO$C 


lO.WVB, . . . ,<stadd,size,vfc> 


WRITE virtual block 
(print buffer contents) 



stadd 



The starting address of the data buffer (may be on a byte 
boundary) . 



size 



vfc 



The data buffer size in bytes (must be greater than 0) 



A vertical format control character from Table 10-4, 
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lO.KIL does not cancel an in-progress request unless the line printer 
is in an off-line condition because of a power failure or a paper jam, 
or because it is out of paper. 

The line printer driver supports no device-specific functions. 



10.4 STATUS RETURNS 

Table 10-3 lists the error and status conditions that are returned by 
the line printer driver described in this chapter. 



Table 10-3 
Line Printer Status Returns 



Code 



IS. sue 



IS.PND 



I E.ABO 



I E . DAA 



lE.DNA 



lE.IFC 



Reason 



Successful completion 

The operation specified in the QIO directive was 
completed successfully. The second word of the 
I/O status block can be examined to determine the 
number of bytes processed, if the operation 
involved writing. 

I/O request pending 

The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 

Operation aborted 

The specified I/O operation was canceled while in 
progress or while in the I/O queue. 

Device already attached 

The physical device unit specified in an 10. ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has 
already attached the desired physical device unit, 
not that the unit was attached by another task. 

Device not attached 

The physical device unit specified an lO.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks. 

Illegal function 

A function code was specified in an I/O request 
that is illegal for line printers. 



(continued on next page) 
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Table 10-3 (Cont.) 
Line Printer Status Returns 



Code 


Reason 


lE.OFL 


Device off line 




The physical device unit associated with the LUN 




specified in the QIO directive was not on line. 




When the system was booted, a device check 




indicated that this physical device unit was not 




in the configuration. 


lE.SPC 


Illegal address space 




The buffer specified for a write request was 




partially or totally outside the address space of 




the issuing task. Alternatively, a byte count of 




was specified. 



10.4.1 Ready Recovery 

If any of the following conditions occur: 

• Paper jam 

• Printer out of paper 

• Printer turned off line 

• Power failure 

the driver determines that the line printer is off line, and the 
following message is output on the operator's console: 



***LPn: 



NOT READY 



The unit number of the line printer that is not ready. 

The driver retries the function that encountered the error condition 
from the beginning, once every second. It displays the message every 
m seconds (m is defined at SYSGEN to be a value less than 256. The 
default is 15) until the line printer is readied. If a power failure 
occurs while printing a line, the entire line is reprinted from the 
beginning when power is restored. 



10.5 VERTICAL FORMAT CONTROL 

Table 10-4 summarizes the meaning of all characters used for vertical 

"For'Tn^l" r< o Tf" ■'' '^ 1 *^^ l-Vio 1 ino r^ v -i « ■*- o >- ari^r /^n^ <-* -P ■i-Vises -^ l-» a *- a «-■ ••- £3 •- s '^s*^ 

be specified as the vfc parameter in an lO.WLB or lO.WVB function. 
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Table 10-4 
Vertical Format Control Characters 



Octal 
Value 



040 



060 



061 



053 



044 



000 



Character 



Blank 



Zero 



One 



Plus 



Dollar 
sign 

Null 



Meaning 



SINGLE SPACE: Output a line feed, print the 
contents of the buffer, and output a carriage 
return. Normally, printing immediately 
follows the previously printed line. 

DOUBLE SPACE: Output two line feeds, print 
the contents of the buffer, and output a 
carriage return. Normally, the buffer 
contents are printed two lines below the 
previously printed line. 

PAGE EJECT: Output a form feed, print the 
contents of the buffer, and output a carriage 
return. Normally, the contents of the buffer 
are printed on the first line of the next 
page. 

OVERPRINT: Print the contents of the buffer 
and perform a carriage return, normally 
overprinting the previous line. 

PROMPTING OUTPUT: Output a line feed and 
then print the contents of the buffer, 

INTERNAL VERTICAL FORMAT: The buffer 
contents are printed without addition of 
vertical format control characters. In this 
mode, more than one line of guaranteed 
contiguous output can be printed per I/O 
request. 



All other vertical format control characters are interpreted as blanks 

(040(8)) . 



10.6 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the line printer driver described 
in this chapter. 



10.6.1 RUBOUT Character 

The line printer driver discards the ASCII character code 177 during 
output, because a RUBOUT on the LSll printer causes a RUBOUT of the 
hardware print buffer. 
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10.6.2 Print Line Truncation 

If the number of characters to be printed exceeds the width of the 
print carriage, the driver discards excess characters until it 
receives one that instructs it to empty the buffer and return to 
horizontal position 1. The user can determine that truncation will 
occur by issuing a Get LUN Information system directive and examining 
word 5 of the information buffer. This word contains the width of the 
print carriage in bytes. 



10.6.3 Aborting a Task 

If a task is aborted while waiting for the line printer to be readied, 
the line printer driver recognizes this fact within 1 second. 
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11.1 INTRODUCTION 

The RSX-llM card reader driver supports the CRll card reader. This 
reader is a virtually jam-proof device that reads EIA standard 
80-column punched cards at the rate of 300 per minute. The hopper can 
hold 600 cards. This device uses a vacuum picker that provides 
extreme tolerance to damaged cards and makes card wear insignificant. 
Cards are riffled in the hopper to prevent sticking. The reader uses 
a strong vacuum to deliver the bottom card. Because it has a very 
short card track, only one card is in motion at a time. 



11.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for card readers. A bit setting of 1 indicates that the 
described characteristic is true for card readers. 

Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 



Bit 


Setting 





1 


1 





2 





3 





4 





5 





6 





7 





8 





9 
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Meaning 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications 
channel 

Device mountable as a FILES-11 volume 

Device mountable 

Words 3 and 4 of the buffer are undefined; word 5 indicates the 
default buffer size, which is 80 bytes for the card reader. 



Bit 


Se 


tting 


10 







11 







12 







13 







14 







15 








11.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
the card reader driver. 



11,3.1 Standard QIO Functions 

Table 11-1 lists the standard functions of the QIO macro that are 
valid for the card reader. 



Table 11-1 
Standard QIO Functions for the Card Reader 



Format 


Function 


QIO$C 


10. ATT,... 


Attach device 


QIO$C 


lO.DET,.. . 


Detach device 


QIO$C 


lO.KIL, . . . 


Cancel I/O requests 


QIO$C 


lO.RLB, , . . ,<stadd,size> 


READ logical block 
(alphanumeric) 


QIO$C 


lO.RVB, . . . ,<stadd,size> 


READ virtual block 
(alphanumeric) 



stadd 



The starting address of the data buffer 
boundary) . 



(may be on 



byte 



size 



The data buffer size in bytes (must be greater than 0) . 



lO.KIL does not cancel an in-progress request unless the card reader 
is in an off-line condition because of a pick, read, stack, or hopper 
check, because of power failure, or because the RESET button has not 
been depressed. 
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11,3.2 Device-Specific QIO Functions 

The device-specific functions of the QIO macro that are valid for the 
card reader are shown in Table 11-2. 



Table 11-2 
Device-Specific QIO Function for the Card Reader 



Format 


Function 


QIOSC lO.ATA, . .. ,<AST addr> 
QIO$C lO.RDB, . . . ,<stadd,size> 


Attach for unsolicited card AST 
Read logical block (binary) 



stadd 



The starting address of the data buffer (may be on a byte 
boundary) . 



size 



The data buffer size in bytes (must be greater than 0) 



11.4 STATUS RETURNS 

A wide variety of error conditions and recovery procedures relate to 
the use of the card reader. This section describes the three major 
ways in which the system reports error conditions. 

1. Lights and indicators on the card reader panel are turned on 
or off to indicate particular operational problems such as 
read, pick, stack, or hopper checks. Switches are available 
to turn the reader power on and off and to allow the user to 
reset after correcting an error condition. 

2. A message is output on the operator's console if operational 
checks or power problems occur. 

3. An I/O completion code is returned in the low-order byte of 
the first word of the I/O status block specified in the QIO 
macro to indicate success or failure on completion of an I/O 
function. 

The following subsections describe each of these returns in detail. 



11.4.1 Card Input Errors and Recovery 

The table included below describes all external lights and switches 
used to indicate to the operator that a hardware problem has occurred 
and must be corrected. There are two classes of hardware errors: 

• Those requiring the operator to ready the reader and try the 
operation again 

• Those requiring the operator to remove the last card from the 
output stacker, to replace it in the input hopper, and to try 
the operation again 
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In the first case, the card reader was unable to read the current 
card. In the second, the card was read incorrectly and must be 
physically removed from the output stacker. The card reader driver 
automatically restarts a read operation within 1 second after the 
cards have been replaced in the input hopper. 

Table 11-3 summarizes the functions of lights and indicators on the 
front panel of the card reader. It discusses common operational 
errors that might be encountered while reading cards and recovery 
procedures associated with these error conditions. 



11.4.2 Ready and Card Reader Check Recovery 

If any of the following conditions occur: 

• Power failure 

• Reset switch not pressed (reader off line) 

• Timing error (Two columns were read before the card reader 
driver input the first column from the card reader.) 

the driver determines that the card reader is not ready, and the 
following message is output on the operator's console: 

*** CRn: — NOT READY 

When a timing error occurs, the operator can proceed with normal card 
reader operation by: 

1. Placing the card reader off line by pressing the STOP switch 

2. Removing the last card read and inserting it where it will be 
the next card read 

3. Placing the card reader on line by pressing the RESET switch 
If any of the following conditions occurs: 

• Pick error (PICK CHECK) 

• Read error (READ CHECK) 

• Output stacker error (STACK CHECK) 

• Input hopper out of cards (HOPPER CHECK) 

• Output stacker full (HOPPER CHECK) 

the driver determines that a card reader check has occurred, and the 
following message is output on the operator's console: 

*** CRn: — READ FAILURE. CHECK HARDWARE STATUS 

where n is the unit number of the card reader that is not ready. The 
operator should correct the error and press RESET: The driver 
attempts the function from the beginning, once every second. It 
displays the message once every m seconds (m is defined at SYSGEN as a 
value less than 256. The default is 15) until the card reader is 
readied. In all cases except pick error, the last card read should be 
reinserted in the input hopper, as described in Section 11.4.1. 
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Table 11-3 
Card Reader Switches and Indicators 



Indicator 



POWER 
Switch 



READ 

CHECK 

Indicator 



Description 



Pushbutton 
indicator 
switch 
(alternate 
action: 
pressed for 
both ON and 
OFF) 



White light 



PICK 

CHECK 
Indicator 



Action 



White light 



Controls application 
of all power to the 
card reader. 

When indicator is 
off, depressing switch 
applies power to 
reader and causes 
associated indica- 
tor to light. 

When indicator is 
lit, depressing 
switch removes all 
power from reader and 
causes indicator to 
go out. 

When lit, this light 
indicates that the 
card just read may be 
torn on the leading or 
trailing edges, or 
that the card may 
have punches in 
column positions 
or 81. 

Because READ CHECK 
indicates an error 
condition, whenever 
this indicator is 
lit, it causes the 
card reader to stop 
operation and extin- 
guishes the RESET 
indicator. 

When lit, this light 
indicates that the 
card reader failed to 
move a card into the 
read station after 
it received a READ 
COMMAND from the 
controller . 



Stops card reader 
operation and extin- 
guishes RESET 
indicator . 



Recovery 



Card may have been 
read incorrectly; 
restore power if 
possible by depress- 
ing the POWER 
switch; insert the 
card again as the 
first card in the 
input hopper, and 
press the RESET 
switch; in some 
cases, it may be 
necessary to 
restart the program. 



Card was read incor- 
rectly; duplicate if 
necessary, insert 
the card again as 
the first card in the 
input hopper, and 
press the RESET 
switch. 



Card could not be 
read; press the 
RESET switch to try 
again or remove the 
cards from the input 
hopper, smooth the 
leading edges, re- 
place, and then 
press the RESET 
switch. 



(continued on next page) 
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Table 11-3 (Cont.) 
Card Reader Switches and Indicators 



Indicator 



STACK 
CHECK 
Indicator 



HOPPER 

CHECK 

Indicator 



STOP 
Switch 



Description 



White light 



White light 



Momentary 
pushbutton/ 
indicator 
switch 
(red light) 



RESET 
Switch 



Momentary 

pushbutton/ 

indicator 

switch 

(green 

light) 



Action 



When lit, this light 
indicates that the 
previous card was not 
properly seated in 
the output stacker 
and therefore may be 
badly mutilated. 

Stops card reader 
operation and ex- 
tinguishes RESET 
indicator. 

When lit, this light 
indicates that either 
the input hopper is 
empty or that the out- 
put stacker is full. 



Recovery 



When depressed, 
immediately lights 
and drops the READY 
line, thereby extin- 
guishing the RESET 
indicator. Card 
reader operation then 
stops as soon as the 
card currently in the 
read station has been 
read. 

This switch has no 
effect on the system 
power; it only stops 
the current operation. 

When depressed and 
released, clears all 
error flip-flops and 
initializes card 
reader logic. Associ- 
ated RESET indicator 
lights to indicate 
that the READY signal 
is applied to the con- 
troller. 

The RESET indicator 
goes out whenever the 
STOP switch is de- 
pressed or whenever 
an error indicator 
lights (READ CHECK, 
PICK CHECK, STACK 
CHECK, or HOPPER 
CHECK) . 



Card may 
read inco 
is not po 
properly 
put stack 
cate the 
is damage 
the card 
the first 
the input 
press the 
switch. 



have been 
rrectly and 
sitioned 
in the out- 
er; dupli- 
card if it 
d; insert 
again as 

card in 

hopper and' 

RESET 



Card may have been 
read incorrectly; 
empty the stacker or 
fill the hopper; in- 
sert the card again 
as the fist card in 
the input hopper and 
press the RESET 
switch. 
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11.4.3 I/O Status Conditions 

The error and status conditions listed in Table 11-4 are returned by 
the card reader driver described in this chapter. 



Table 11-4 
Card Reader Status Returns 



Code 



IS. sue 



IS.PND 



IE. ABO 



lE.DAA 



lE.DNA 



IE. EOF 



lE.IFC 



IE. NOD 



Reason 



Successful completion 

The operation specified in the QIO directive was 
completed successfully. The second word of the 
I/O status block can be examined to determine the 
number of bytes processed, if the operation 
Involved reading. 

I/O request pending 

The operation specified in the QIO directive has 
not yet been executed. The I/O status block is 
filled with Os. 

Operation aborted 

The specified I/O operation was cancelled while in 
progress or while still in the I/O queue. 

Device already attached 

The physical device unit specified in an 10. ATT 
function was already attached by the issuing task. 

Device not attached 

The physical device unit specified in an lO.DET 
function was not attached by the issuing task. 
This code has no bearing on the attachment status 
of other tasks. 

End-of-file encountered 

An end-of-file control card was recognized. 

Illegal function 

A function code was specified in an I/O request 
that is illegal for card readers. 

Buffer allocation failure 

Dynamic storage space has been depleted, and there 
was insufficient buffer space available to 
allocate a card buffer (that is, cards are read 
into a driver buffer, translated, and then moved 
to the user buf ferl . 



(continued on next page) 
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Table 11-4 (Cont.) 
Card Reader Status Returns 



Code 


Reason 


lE.OFL 
lE.SPC 


Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not 
in the configuration. 

Illegal address space 

The buffer specified for a read request was 
partially or totally outside the address space of 
the issuing task. Alternatively, a byte count of 
was specified. 



11.5 FUNCTIONAL CAPABILITIES 

The card reader driver can perforin the following functions: 

1. Read cards in DEC026 format and translate to ASCII 

2. Read cards in DEC029 format and translate to ASCII 

3. Read cards in binary format 

If the QIO macro specifies the lO.RLB or lO.RVB function, the driver 
interpets all data as alphanumeric (026 or 029 format). As explained 
below, control characters indicate whether 026 or 029 is desired. If 
the QIO macro specifies lO.RDB, the driver interprets all data, 
including 026 and 029 control characters, as binary. 



11.5.1 Control Characters 

Table 11-5 lists the multipunched cards that the card reader driver 
recognizes as control characters. They are never transferred to the 
user's buffer or included in the count of transferred bytes in 
alphanumeric mode. In binary mode, the only control card recognized 
is binary EOF. 



DEC026 

bootst 

a cont 

encoun 

DEC029 

card 

subseq 

charac 

effect 



IS 

rapped 
rol ca 
tering 
forma 
overr 
uent 
ters 
even 



the de 
This 
rd ind 
a DECO 
t unles 
ides 
cards 
are ad 
when th 



fault transl 
mode remains 
icating that 
29 control ca 
s another DEC 
the 029 mod 
are to be 
dressed to 
e reader is a 



ation mode 
in effect 
DEC029 c 
rd, the dri 
026 control 
e specific 
translated 
the card r 
ttached and 



when the 
until explicitl 
ards will fol 
ver translates 

card is encoun 
ation and ind 

in 026 forma 
eader itself, a 

subsequently d 



system is 
y changed by 
low. After 
all cards in 
tered. This 
icates that 
t. Control 
nd remain in 
etached . 
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The default condition can easily be changed from DEC026 to DEC029 by 
reading a 029 control card, and then saving the system with the MCR 
SAV command . 



Table 11-5 
Card Reader Control Characters 



Punches 


Columns 


Meaning 


12-11-0-1-6-7-8-9 
12-11-0-1-6-7-8-9 

12-2-4-8 
12-0-2-4-6-8 


1 

(All 8 punches in 
the first 8 columns) 

1 

1 


End-of-file (alphanumeric) 
End-of-file (binary) 

026-coded cards follow 
029-coded cards follow 



11.6 CARD READER DATA FORMATS 

The card reader reads data in either alphanumeric or binary format. 

11.6.1 Alphanumeric Format (026 and 0211) 

Table 11-6 summarizes the translation from DEC026 or DEC029 card codes 
to ASCII. 



11.6.2 Binary Format 

In RSX-llM binary format, the data are not packed, but are transferred 
exactly as read, one card column per word. Because each word has 16 
bits and each card column represents only 12, the data from the column 
are stored in the rightmost 12 bits of the word. The word's remaining 
four bits contain Os. 



11.7 PROGRAMMING HINTS 



This section 
considerations 
In this chapter, 
error-recovery 
point of view. 



contains information on important programming 

relevant to users of the card reader driver described 

Section 11.4 contains information on operational 

procedures that might be important from a programming 



11.7.1 Input Card Limitation 

Only one card can be read with a single QIC macro call. A request to 
t.t^GKA iiiOtc uiiaii ov wy L-cro ul ^uj-ilmnis, uiie xenyuii uj- ca single ucjra, Qoes 
not result in a multiple card transfer. Only 80 columns are 
processed. It is possible to read fewer than 80 columns of card input 
with a QIO read function. For example, the user can specify that only 
the first 10 columns of each card are to be read. 
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11.7.2 Aborting a Task 

If a task waiting for the card reader to be readied is aborted, the 
card reader driver recognizes this fact within 1 second. 



Table 11-6 
Translation from DEC026 or DEC029 to ASCII 





Non- 








Non- 








Parity 








Parity 






Character 


ASCII 


DEC029 


DEC026 


Character 


ASCII 


DEC029 


DEC026 




173 


12 


12 


1 


054 


8 3 


8 3 




175 


11 


11 


- 


055 


11 


11 


SPACE 


040 


none 


none 


• 


056 


12 8 3 


12 8 3 


1 


041 


12 8 7 


12 8 7 


/ 


057 


1 


1 


If 


042 


8 7 


8 5 





060 








# 


043 


8 3 


8 6 


1 


061 


1 


1 


$ 


044 


11 8 3 


11 8 3 


2 


062 


2 


2 


% 


045 


8 4 


8 7 


3 


063 


3 


3 


AND 


046 


12 


11 8 7 


4 


064 


4 


4 


1 


047 


8 5 


8 6 


5 


065 


5 


5 


( 


050 


12 8 5 


8 4 


6 


066 


6 


6 


) 


051 


11 8 5 


12 8 4 


7 


067 


7 


7 


* 


052 


11 8 4 


11 8 4 


8 


070 


8 


8 


+ 


053 


12 8 6 


12 


9 


071 


9 


9 


. 


072 


8 2 


11 8 2 


M 


115 


11 4 


11 4 


1 


073 


11 8 6 


8 2 


N 


116 


11 5 


11 5 




074 


12 8 4 


12 8 6 





117 


11 6 


11 6 


— 


075 


8 6 


8 3 


P 


120 


11 7 


11 7 


> 


076 


8 6 


11 8 6 


Q 


121 


11 8 


11 8 


7 


077 


8 7 


12 8 2 


R 


122 


11 9 


11 9 


la 


100 


8 4 


8 4 


S 


123 


2 


2 


A 


101 


12 1 


12 1 


T 


124 


3 


3 


B 


102 


12 2 


12 2 


U 


125 


4 


4 


C 


103 


12 3 


12 3 


V 


126 


5 


5 


D 


104 


12 4 


12 4 


W 


127 


6 


6 


E 


105 


12 5 


12 5 


X 


130 


7 


7 


F 


106 


12 6 


12 6 


Y 


131 


8 


8 


G 


107 


12 7 


12 7 


Z 


132 


9 


9 


H 


110 


12 8 


12 8 


[ 


133 


12 8 2 


11 8 5 


I 


111 


12 9 


12 9 


\ 


134 


8 2 


8 7 


J 


112 


11 1 


11 1 


] 


135 


11 8 2 


12 8 5 


K 


113 


11 2 


11 2 


" or 


135 


11 8 7 


8 5 


L 


114 


11 3 


11 3 


or 


137 


8 5 


8 2 



11-10 



CHAPTER 12 
MESSAGE-ORIENTED COMMUNICATION DRIVERS 



12.1 INTRODUCTION 

RSX-llM supports a variety of communication line interfaces: 
synchronous and asynchronous, single-line and multiplexers, 
character-oriented and message-oriented. These are used for terminal 
communications, remote job entry, multicomputer interfaces, and 
laboratory and industrial control communications. Communications line 
interfaces can be roughly divided into two categories: 

• Terminal (character-oriented) communications devices 

• Multicomputer (message-oriented) communications devices 

Chapters 1, 2, and 3 describe the character-oriented asynchronous 
communications line interfaces used primarily for terminal 
communications. The Terminals and Communications Handbook contains 
more detail on these devices. This chapter describes in some detail 
the RSX-llM message-oriented synchronous and asynchronous 
communication line interfaces. These are used most frequently in 
multicomputer communications. 

Character-oriented communications devices include the DHll, DJll, 
DLll-A, DLll-B/C/D, and DZll interfaces. These are asynchronous 
multiplexers and single-line interfaces used almost exclusively for 
terminal communications. Transfers on all of these interfaces are 
performed one character at a time. None of the interfaces in this 
category has a driver of its own (that is, they are supported by the 
terminal driver) , and none can be accessed directly as RSX-llM 
devices. 

Message-oriented communications line interfaces are used primarily to 
link two separate but complementary computer systems. One system must 
serve as the transmitting device and the other as the receiving 
device. Devices in this category include the synchronous and 
asynchronous single-line interfaces summarized in Table 12-1. 

The message-oriented communication line interfaces are used primarily 
to transfer large blocks of data. 

Whereas the character-oriented interfaces can only be accessed 
indirectly through the terminal driver, the DAll-B, DLll-E, DMCll, 
DPll, DQll, DUll, and DUPll allow I/O requests to be queued directly 
for them. These devices have drivers of their own and can be accessed 
by means of the logical device names listed in Table 1-1. These names 
can be used in assigning LUNs with the Assign LUN system directive, at 
task build, or with the REASSIGN MCR command. The following 
subsections briefly discuss the message-oriented interfaces supported 
for RSX-llM. 
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Table 12-1 
Message-Oriented Communication Interfaces 



Model 


Type 


Rate 
(KBaud) 


Duplex 
Half/Full 


Data block 
(words) 


Synchronous 
Character 


DAll-B^ 


Paralle 


L 


500 


X 


32K 


No 


DL11-e2 


Serial , 


asynchronous 


0.05-9.6 


X X 


32K 


Programmable 


DMCll 


Serial , 


synchronous 


19.2-1000 


X X 


8K 


No 


DPlll 


Serial , 


synchronous 


2-19.2 


X X 


32K 


Programmable 


DQlll 


Serial, 


synchronous 


2.4-1000 


X X 


32K 


Programmable 


DUlll 


Serial , 


synchronous 


0.05-9.6 


X X 


32K 


Programmable 


DUPll 


Serial , 


synchronous 


0.05-9.6 


X X 


32K 


Programmable 



1. Support is not provided on RSX-llM-PLUS systems. 

2. DLll-E support is provided on RSX-llM-PLUS systems using the full-duplex 
terminal driver only. 



12.1.1 DAll-B Parallel Interface 

The DAll-B provides a bit-parallel, direct memory access interface 
between two PDP-11 computer systems. Data transfers are performed a 
word at a time and are made directly between the memories of the two 
systems. The maximum transfer rate is 500,000 baud, and is adjustable 
by the user to match the system configuration requirements. Being a 
parallel device, the DAll-B does not utilize sync characters. The 
interface is half-duplex and transfers data in blocks of up to 32K 
words. 

The DAll-B requires two cooperating computers to effect a data 
transfer. In order to control the physical link between the 
computers, the device driver contains its own simple line protocol. 
This protocol requires one system to issue a receive QIO and the other 
to issue a transmit QIO before any data is actually transferred. 



12.1.2 DLll-E Asynchronous Line Interface 

The DLll-E is an asynchronous, serial-bit, single-line interface. It 
is a block-transfer device used for remote terminal and multicomputer 
communications. Baud rates are selectable between 50 and 9600, and 
full data-set control is supported.! 



1. Software support for data-set control consists of interlocking RTS 
and CTS for data transmission, and the setting of DTR (data terminal 
ready) to enable auto-answer modems to answer incoming calls. DTR is 
set when an lO.INL QIO (initialize) is issued. 
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12.1.3 DMCll Synchronous Line Interface 

The DMCll provides a direct memory access interface between two PDP-11 
computer systems using the DDCMP line protocol, thus delivering high 
throughput and reliability while simplifying programming. The DMCll 
supports Non-Processor Request (NPR) data transfers of up to 8K words 
at rates of 1,000,000 baud for local operation (over coaxial cable) 
and 19,200 baud for remote operation (using modems). Both full- and 
half-duplex modes are supported. The DMCll also implements remote 
load detect, allowing it to reinitialize a halted computer system. 



12.1.4 DPll Synchronous Line Interface 

The DPll provides a program interrupt interface between a PDP-11 and a 
serial synchronous line. This interface facilitates the use of the 
PDP-11 in remote batch processing, remote data collection, and remote 
concentration applications. The modem control feature allows the DPll 
to be used in switched or dedicated configurations. 

On the DPll, baud rates are selectable between 2000 and 19,200. The 
programmer can select a specific sync character that is used to 
synchronize the transmitting and receiving systems. 



12.1.5 DQll Synchronous Line Interface 

The DQll provides a direct memory access interface between a PDP-11 
and a serial synchronous line. The direct memory access 
characteristic of the DQll allows the device to operate at speeds 
higher than those of program interrupt devices, and with a lower 
interrupt overhead. Modem control of the DQll allows the device to be 
used in switched or dedicated configurations. 

The DQll handles data rates from 2400 baud to 1,000,000 baud. The 
limiting rate is determined by the modem and data set interface level 
converters. 

The DQll sync character is programmable in the same manner as the DPll 
and the DUll. The maximum data block length transmitted is 65,536 
characters. 



12.1.6 DUll Synchronous Line Interface 

The DUll synchronous line interface is a single-line communications 
device that provides a program-controlled interface between the PDP-11 
and a serial synchronous line. The PDP-11 can be interfaced with a 
high-speed line to perform remote batch processing, remote data 
collection, and remote concentration applications. Modem control is a 
standard feature of the DUll and allows the device to be used in 
switched or dedicated configurations. The DUll transmits data at a 
maximum rate of 9600 baud; this rate is limited by modem and data set 
interface level converters. 

The DUll can be programmed to accept any user-defined sync character. 
The use of the sync character is the same for the DUll and the DPll. 
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12.1.7 DUPll Synchronous Line Interface 

The DUPll is identical to the DUll, except that it incorporates 
hardware to perforin cyclic redundancy checking. 



12.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for message-oriented communication interfaces. A bit 
setting of 1 indicates that the described characteristic is true for 
the interfaces described in this chapter. 

Bit Setting Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File-structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications channel 

Device mountable as a FILES-11 volume 

Device mountable 

Words 3 and 4 are undefined, and word 5 has a special meaning for the 
DLll-E, DQll, DPll, and the DUll interfaces. Byte of word 5 
contains the number of sync characters to be transmitted before a 
synching message (for example, after line turn-around in half-duplex 
operation) , and byte 1 is used as a sync counter. 









1 





2 





3 





4 





5 





6 





7 





8 





9 





10 





11 





12 





13 


1 


14 





15 


1 
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12.3 QIO MACRO 

This section summarizes the standard and device-specific functions of 
the QIO macro that are valid for the communication interfaces 
described in this chapter. 



12.3.1 Standard QIO Functions 

Table 12-2 lists the standard functions of the QIO macro that are 
valid for the communication devices. 



Table 12-2 
Standard QIO Functions for Communication Interfaces 



Format 


Function 


QIO$C 


10. ATT, . .. 


Attach device-'- 


QIO$C 


lO.DET, . . . 


Detach device 


QIO$C 


lO.KIL, . . . 


Cancel I/O requests 


QIO$C 


lO.RLB, . . . ,<stadd,size> 


READ logical block (stripping 
sync) 


QIO$C 


lO.WLB, . . . ,<stadd ,size> 


WRITE logical block (preceded by 
syncs) 



1. Only unmounted channels may be attached. An attempt to attach 
a mounted channel will result in an lE.PRI status being returned 
in the I/O status doubleword. 



stadd 



The starting address of the data buffer (may be on a byte 
boundary) . 



size 



The data buffer size in bytes (must be greater than 0) 



12.3.2 Device-Specific QIO Functions 

The specific functions of the QIO macro that are valid for the 
communication line interfaces are shown in Table 12-3. 
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Table 12-3 
Device-Specific QIC Functions for Communication Interfaces 



Format 


Function 


QIO$C lO.FDX 




Set device to full-duplex mode; 
Not applicable to DAll-B 


QIO$C lO.HDX,, 


. . ,<stat,mode> 


SET device to half-duplex mode; 
Not applicable to DAll-B 


QIOSC lO.INL,, 




Initialize device and set device 
characteristics 


QIO$C lO.RNS,. 


. . ,<stadd,size> 


READ logical block, without 
stripping sync characters 
(transparent mode); Not applicable 
to DQll; for DAll-B and DMCll , 
treated like lO.RLB 


QIO$C lO.SYN,. 


. . ,<syn> 


SPECIFY sync character; not 
applicable to DAll-B or DMCll 


QIO$C lO.TRM,, 


• • 


Terminate communication, 
disconnecting from physical channel 


QIO$C lO.WNS,, 


. . ,<stadd,size> 


WRITE logical block without 
preceding sync characters 
(transparent mode); for DAll-B and 
DMCll, treated like lO.WLB 



stadd 



The starting address of the data buffer (may be on a byte 
boundary) . 



size 



syn 



The data buffer size in bytes (must be greater than 0) 



The sync character, expressed as an octal value. 



Stat 



The station assignment (primary or secondary) 



mode 



The transmission mode (normal or maintenance) 



The device-specific functions listed in Table 12-3 are described in 
greater detail below. 
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12.3.2.1 lO.FDX - The lO.FDX QIC function is used to set the mode on 
a DLll-E, DPll, DQll, DUll, DUPll, or DMCll unit to full-duplex. The 
lO.FDX function code can be combined (ORed) with the lO.SYN function 
code, if desired, to set the operational characteristics of the 
physical device unit. 



12.3.2.2 lO.HDX - The lO.HDX QIO function is used to set the mode on 
a DLll-E, DPll, DQll, DUll, DUPll, or DMCll unit to half-duplex. The 
lO.HDX function code can be combined (ORed together) with the lO.SYN 
function code, if desired, to set the operational characteristics of 
the physical device unit. 

Setting half-duplex on the DMCll also involves setting the station 
assignment (primary/secondary) and may include selecting maintenance 
mode (MOP) as opposed to normal mode. The station assignment is 
included in optional QIO parameter pi. A indicates primary station 
and a nonzero indicates secondary station. The DMCll works properly 
if both ends are primary stations or if there is one primary and one 
secondary station. It does not work if both ends are secondary 
stations. Optional QIO parameter p2 is used to select the mode. A 
selects normal mode and a nonzero selects MOP mode. A DMCll in MOP 
mode cannot communicate with a DMCll in normal mode. 



12.3.2.3 lO.INL and lO.TRM - These two QIO functions have the same 
function code but different modifier bits. lO.INL is used to 
initialize a physical device unit for use as a communications link. 
It turns the device on line, sets device characteristics, and ensures 
that the appropriate data terminal is ready. lO.TRM disconnects the 
device. If the device has a dial-up interface, it also hangs up the 
line. 



12.3.2.4 lO.RNS - The lO.RNS QIO function is used to read a logical 
block of data, without stripping the sync characters that may precede 
the data. A similar function is lO.RLB, which is nontransparent , in 
that it causes sync characters preceding the data message to be 
stripped. lO.RLB is used at the start of a segmented data request, in 
which the block might have the following layout: 



s 


s 


H 


H 


H 


H 


CS 


CS 


DATA 


CS 



12 3 4 5 6 7 8 



CS 



A sync character. 



A header character. 



A validity check character. 
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The programmer must strip sync characters from the beginning of a data 
block in this way. Stripping only at the beginning of a read allows a 
later character which happens to have the same binary value as a sync 
character to be read without stripping. lO.RLB is used to read a 
logical block with leading sync characters stripped; lO.RNS is used 
to read the block without stripping leading sync characters. Since 
the DAll-B is a parallel device and there are no sync characters, it 
treats the latter as if it were lO.RLB. Generally, lO.RLB should be 
used. 



12.3.2.5 lO.SYN - This QIC function allows the programmer to specify 
the sync character to be recognized when an lO.RLB or lO.WLB function 
is performed. lO.SYN can be combined (ORed together) with lO.HDX or 
with lO.FDX to set the characteristics of the physical device unit. 



12.3.2.6 lO.WNS - This QIO function causes a logical block to be 
written with no preceding sync characters. To ensure that the two 
systems involved in a communication are synchronized, two or more sync 
characters are transmitted by one system and received by the other 
before any other message can be sent. lO.WLB is used to write a block 
of data, preceded by sync characters; lO.WNS is used to perform a 
block transfer without sending sync characters first. Since the 
DAll-B is a parallel device and there are no sync characters, it 
treats the latter as if it were lO.WLB. Generally, lO.WLB should be 
used. 



12.4 STATUS RETURNS 



The error and status conditions listed in Table 12-4 are 
the communication drivers described in this chapter. 



returned by 



Table 12-4 
Communication Status Returns 



Code 


Reason 


IS. sue 


Successful completion 




The operation specified in the QIO directive was 
completed successfully. The second word of the I/O 
status block can be examined to determine the number 
of bytes processed, if the operation involved reading 
or writing. 


IS.PND 


I/O request pending 




The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 



(continued on next page) 
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Table 12-4 (Cont.) 
Communication Status Returns 



Code 



Reason 



lE.BCC Block check error 

When the Cyclic Redundancy Check (CRC) option is 
present on the DQll, a check character is appended to 
each message transmitted. The receiver of the 
messages recalculates the check character and 
compares it with the one transmitted. This error 
code is returned when the two check characters do not 
match, and represents a transmission error. 

IE. CNR Connection rejected 

(DMCll only.) The DMCll has detected that the device 
on the other end of the line has restarted itself. 
The user can recover by issuing lO.INL (initialize), 
and then reissuing the QIO in question. 

IE. DAG Data overrun 

Due to UNIBUS traffic or a modem problem, the DQll 
controller was unable to maintain the data rate 
required to prevent data loss (that is, the receipt 
of another byte before processing of a previous byte 
was completed) . 

lE.DNR Device not ready 

The physical device unit specified in the QIO 

directive was not ready to perform the desired I/O 

operation. This code is returned to indicate one of 
the following conditions: 

• The physical device unit could not be initialized 
(that is, the circuit could not be completed) . 

• The transmission of a character was not followed 
by an interrupt within the period of time selected 
as the device time-out period. This time-out 
occurs only when a transmission is in progress and 
the interrupt marking completion of a message does 
not occur. The appropriate response to this 
condition is to attempt to resynchronize the 
device by initializing and accepting the next 
request. A time-out does not occur on a read. If 
the receiving device is not ready, the transfer 
will not be initiated by the transmitting device. 
Once the transfer is initiated, however, it will 
complete either by satisfying the requested byte 
count or by timing out. 



(continued on next page) 
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Table 12-4 (Cont.) 
Communication Status Returns 



Code 



Reason 



IE. IPC 



lE.OFL 



lE.SPC 



lE.VER 



IE. ABO 



lE.RSU 



lE.TMO 



Illegal function 

A function code was specified in an I/O request that 
is illegal for message-oriented communication 
devices . 

Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. 

Illegal address space 

The buffer specified for a read or write request was 
partially or totally outside the address space of the 
issuing task. Alternatively, a byte count of was 
specified. 

Nonrecoverable error (DAll-B only) 

The data transfer terminated before all of the data 
has been transmitted. The error' code is returned on 
transmit when both systems attempt to transmit at the 
same time. This condition is detected by the device 
protocol. The error code is returned on receive when 
the transmit data count of the transmitting side does 
not equal the data count specified by the receive 
QIO. 

Operation Aborted 

The specified I/O operation was canceled by lO.KIL 
while in progress or while still in the I/O queue. 

Sharable Resources in use 

The task attempted to allocate Unibus Mapping 
Registers. All UMRs were allocated to other tasks 
and were unable to complete the transfer. 

Timeout Error 

The physical device unit associated with the LUN 
specified in the QIO directive timed out. This 
occurs during a data transfer operation when thetask 
does not receive an interrupt within a specified 
amount of time. 
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12.5 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the message-oriented communication 
interfaces described in this chapter. 



12.5.1 'Transmission Validation 

Because there is no way for the transmitting device to verify that the 
data block has successfully arrived at the receiving device unless the 
receiver responds, the transmitter assumes that any message that is 
clocked out on the line (without line or device outage) has been 
successfully transmitted. As soon as the receiver is able to satisfy 
a read request, it returns a successful status code (IS.SUC) in the 
I/O status block. Of course, only the task receiving the message can 
determine whether the message has actually been transmitted 
accurately. 

The receiving device should be ready to receive data (with a read 
request) at the time the transmission is sent. 



12.5.2 Redundancy Checking 

By the nature of message-oriented communications, only the task that 
receives a communication can determine whether the message was 
received successfully. The transmitter simply transfers data, without 
validation of any kind. It is therefore the responsibility of the 
communicating tasks which use the device to check the accuracy of the 
transmission. A simple validity check is a checksum-type longitudinal 
redundancy check. A better approach to validating data is the use of 
a cyclic redundancy check (CRC) . A CRC can be computed in software or 
with a hardware device, such as the KG-11 communications arithmetic 
option. 

Both DQll and DUPll incorporate hardware to compute a CRC. The DQll 
CRC hardware requires an extra system unit. 



12.5.3 Half-Duplex and Full-Duplex Considerations 

Because there is a single I/O request queue, only one QIO request can 
be performed at a time. It is therefore not possible, through QIOs, 
for a device to send and receive data at the same time. Also, since 
timeouts are not set for receive functions, a receive QIO is 
terminated only by receiving a message from the remote system, or by 
issuing an lO.KIL QIO for the device. Therefore, if no message is 
transmitted by the remote system, a receive will not terminate, and no 
further I/O can be performed on that device until the receive is 
killed by issuing an lO.KIL QIO. 

Both half-duplex and full-duplex lines can be used with the DLll-E, 
DMCll, DPll, DQll, DUll, and DUPll. The mode is settable by using 
lO.FDX for full-duplex and lO.HDX for half-duplex. In half-duplex 
mode, the modem signal RTS (Request To Send) is cleared after each 
"transmit message." In full-duplex, this signal is always left on. 
Using full-duplex mode eliminates modem delays in transmission, but 
requires full-duplex hardware and communication links. 
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Only half-duplex mode is available with the DAll-B because of the 
nature of the hardware. 

The DMCll Driver maintains both transmits and receives separately in 
its own internal queues. Thus, it is a full-duplex driver. There is 
no limit on the number of outstanding I/O requests that can be active 
at any given time. The DMCll hardware, however, allows a maximum of 
only seven transmits and seven receives to be active at any time. The 
driver gives the first seven transmits (or receives) direct^^y to the 
DMCll and queues the eighth and subsequent transmits (or receives) 
internally until the DMCll acknowledges a successful I/O request. 
When running on an 11/70, the driver gives only two transmits (or 
receives) to the DMCll because each request requires a UNIBUS mapping 
register. The DMCll driver is assigned five UMRs : one for base 
table(s), two for active transmits, and two for active receives. 



12.5.4 Low-Traffic Sync Character Considerations 

If message traffic on a line is low, each message sent from a 
communications device should be preceded by a sync train. This 
enables the controller to resynchronize if a message is "broken" (that 
is, part or all of it is lost in transmission). Correspondingly, 
every message received by a communications device under low-traffic 
conditions, when messages are not contiguous (back-to-back) , should be 
read with an lO.RLB (read, strip sync) function. This requires that 
the first character in the data message itself not have the binary 
value of the sync character. 



12.5.5 Vertical Parity Support 

Vertical parity is not supported by the DAll-B, DLll-E, DPll, DQll, or 
DUll. Codes are assumed to be 8-bit only. 



12.5.6 Powerfail with DMCll 

The DMCll currently cannot recover after a power failure because the 
RAM in its internal microprocessor is erased when power fails. Any 
I/O requests outstanding at the time of a power failure will return 
IE. ABO. These requests must be reissued after initializing the DMCll 
(lO.INL) . 



12.5.7 Importance of lO.INL 

After the type of communication line has been determined, and after 
lO.SYN has specified the sync character, it is extremely important 
that lO.INL be issued before any transfers occur. This ensures that 
appropriate parameters are initialized and that the interface is 
properly conditioned. Note that lO.INL provides the only means of 
setting device characteristics, such as sync character. For this 
reason, lO.INL should always be used immediately prior to the first 
transfer over a newly activated link. 
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Tasks sending messages to the DMCll should begin by terminating and 
reinitializing the device (IO.TRM,IO.INL) .1 lO.INL must be issued 
after each lO.KIL (which effectively kills the DMCll), after 
power-fail, and upon receipt of any error code. 



12.6 PROGRAMMING EXAMPLE 

The following example illustrates the initialization, setting of 
device parameters, and transmission of a block of data on a 
message-oriented communication device. 

.MCALL ALUN$S,QIO$S 



ALUN$S #1,#"XP,#0 

QIO$S #I0.HDX!I0.SYN,<#1,,,,,#2 26> 

QIO$S #I0.INL,#1 



USE LUNl FOR DPll 
SET DEVICE PARAMETERS 
PUT DEVICE ON LINE 



QIO$S #IO.WLB,#1,,,<#TXSTS,#TXAST,#TXBUF,#100>; SEND A BLOCK 



TXAST: CMPB #IS. SUC&377,@ (SP) + 



BEQ 10$ 



WAS DATA CLOCKED OU 

SUCCESSFULLY? 

IF SO, SET UP FOR NEXT 

BLOCK 



1. Note that this will cause the error IE. CNR to be 
I/O outstanding on the other end of the line. 



returned on any 
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CHAPTER 13 
PCLll PARALLEL COMMUNICATIONS LINK DRIVERS 



13.1 INTRODUCTION 



PCLll Parallel Communications 

RSX-llM-PLUS systems by two 

transmitter function and the 

function. The PCLll-B is a 

time division multiplexed (TDM) 

computers can transfer data to each other. 

transmitter, receiver, and master section. 



Link hardware is supported on 

drivers. One driver supports the 

other driver supports the receiver 

hardware interface that functions as a 

interface over which several PDP-11 

Each PCLll-B consists of a 

The transmitter section 



can transfer parallel 16-bit words along the TDM bus to a receiver 
section of a separate PCLll-B on a different PDP-11 computer's UNIBUS. 
One of the PCLll-B units attached to the TDM bus must have its master 
section enabled to effect the data transfer. 



13.1.1 PCLll-B Hardware 



Each PCLll-B transmitter and receiver section has a un 
address (hardware-configured) . When a master section 
places a transmitter address on the TDM bus for a per 
called a timeslice. During the timeslice, the address 
can address the desired receiver section and transmit on 
transmitter waits for the receiver to acknowledge 
indication that the word was not accepted. If the 
accepted, it will normally retransmit the word on the 
timeslice. Thus, a message up to 32k words long can be 
a receiver one word at a time during the time in which 
TDM transactions are multiplexed for other PCLll-B devic 



ique TDM bus 
is enabled, it 
iod of time, 
ed transmitter 
e word; the 
the word or an 

word is not 
next available 
transmitted to 

other similar 
es. 



13.1.2 PCLll Transmitter Driver 

The PCLll transmitter driver provides two basic functions. First, it 
must receive data sent by the attached task and store it in a silo 
buffer in the PCLll hardware. Then, the driver passes proper receiver 
address and command information to the PCLll transmitter hardware to 
effect the actual transfer over the TDM bus. 



13.1.3 PCLll Receiver Driver 

The PCLll receiver driver also performs two basic functions. First, 
it must remove data from the receiver silo and send it to the 
connected task. In addition, the receiver driver must acknowledge a 
transmitter when a data transmission is requested by that transmitter. 
Subsequent requests by other transmitters on the TDM bus are ignored 
until all message transactions with the current transmitter are 
completed . 
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13.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains the following 
information for the PCLll transmitter and receiver drivers. A setting 
of 1 indicates that the described characteristics is true for PCLll 
transmitter and receiver drivers. 

Meaning 

Record-oriented device 

Carriage-control device 

Terminal device 

File-structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 

Input spooled device 

Output spooled device 

Pseudo device 

Device mountable as a communications channel 

Device mountable as a FILES-11 volume 

Device mountable 

Word 3 contains device driver-specific information, as follows: 

Transmitter driver: 

The low byte of word 3 contains the number of transmit retries 
remaining after completing the current data transmit function if 
the current data transmit function attempt is not accepted by the 
addressed receiver. The high byte of word 3 is undefined. 

Receiver driver: 

The low byte of word 3 contains the index of the current state of 
the receiver driver. These states are primarily used for 
diagnostic purposes and are defined as follows: 

Index Value Meaning 

No task is connected. 

+2 Task connected but not triggered. 

+4 Task triggered and waiting for 10. RTF or 

lO.ATF function. 
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Bit 


Setting 





1 


1 





2 





3 





4 





5 


1 


6 





7 





8 





9 





10 





11 





12 





13 





14 





15 
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Index Value Meaning 

+6 Task triggered and timed out while waiting for 

ID. RTF or lO.ATF function. 

-2 lO.ATF function is in progress. 

-4 Task connected, not triggered, and has an 

lO.ATF function in progress. 

-6 An 10. RTF function is in progress. 

The high byte of word 3 is undefined. Word 4 is undefined. Word 5 is 
the default buffer size in bytes. For the PCLll, this value is 64 
bytes. 



13.3 QIO MACRO — PCLll TRANSMITTER DRIVER FUNCTIONS 
13.3.1 Standard QIO Functions 

Table 13-1 lists the standard functions of the QIO macro that are 
valid for the PCLll transmitter driver. 



Table 13-1 
Standard QIO Functions for PCLll Transmitters 



Format 


Function 


QIO$C 10. ATT,... 
QIO$C lO.DET,... 
QIO$C lO.KIL,... 


Attach device 
Detach device 
Cancel I/O request 



13.3.2 Device-Specific QIO Functions 



Table 13-2 lists the device-specific functions of the QIO macro that 
are valid for the PCLll transmitter driver. 



Table 13-2 
Device-Specific QIO Functions for PCLll Transmitters 



Format 


Function 


QIO$C lO.ATX,. ..,<stadd,size. 




f lagwd, id, retries, retadd> 


Attempt message transmission 


QIO$C 10. SEC,..., 


Sense master section status 


QIO$C lO.STC, . . . ,<stadd,size. 




[state] , [mode] , ,retadd> 

1 1 


Set master section characteristics 
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stadd 



The starting address of a data buffer. (Its description and 
function is dependent upon the specific QIO function.) 



size 



The data buffer size in bytes. (Its description and function is 
dependent upon the specific QIO function.) 



flagwd 



id 



The value of the flagword that is to precede the message being 
sent. The flags specify the desired receiver function as defined 
by the user's protocol. 



The identifier of the CPU to which the message is to be sent. 
This identifier is the desired receiver's TDM bus address. It 
appears in the high byte of the first word of the master section 
I/O status block. The identifier number is an octal value 
contained in the high byte of the parameter word. For example, 
receiver number 1 is specified as 400, receiver number 2 is 
specified as 1000, and so forth. 



retries 



The number of retries that will be attempted, following the first 
attempt, that will be performed if the first attempt is 
unsuccessful, or upon detecting transmission errors or master 
down conditions, before returning error status to the calling 
task. 



retadd 



The starting address of a 7-word buffer into which the contents 
of the six transmitter registers and the transmitter 
master/maintenance register are moved prior to returning to the 
calling task. Information describing the contents of these 
registers can be obtained by referring to the hardware 
documentation supplied with the PCLll option. 



state 

The desired state setting for the transmitter, as follows; 

Parameter 

Specified State 

SS.MAS TDM bus master 

SS.NEU Neutral (default state) 
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mode 



The desired mode setting for allocating transmitter timeslices on 
the TDM bus, as follows: 



Parameter 
Entered 

MS.AUT 

MS. ADS 



Mode 
Auto addressing (default mode) 
Address silo 



13.3.2.1 10. ATX - This I/O function requests an attempt to transmit a 
message to a specified CPU. The message to be' transmitted is 
contained in a data buffer starting at the address specified in the 
stadd parameter. This address must be on a word boundary. The data 
buffer size specified in the size parameter must be an even, positive 
value. The flagword parameter contains user-defined information that 
the receiving task will use in determining whether to accept or reject 
the message. The id parameter is the receiver TDM bus address. The 
task uses this address to direct a message to a specific CPU. Other 
parameters are as previously described. 



13.3.2.2 10. SEC - This I/O function is used to sense the master 
section status. Upon successful completion of this function, the I/O 
status block will contain a typical I/O status code (IS.SUC) return in 
the low byte of the first word, and current Transmitter 
Master/Maintenance Register (TMMR) contents in the second word, as 
follows: 



Status Code 



Current TMMR Contents 



NOTE 

The optional isb parameter (see Section 
1.5.1) must be included in this QIO 
request. 



13.3.2.3 lO.STC - This I/O function sets the master section 
operational characteristics. lO.STC can only be issued by a 
privileged task. Correct use of the function depends upon the current 
(or specified) operating state of the master section and proper use of 
parameters. Each parameter is used as described in the following 
paragraphs. Refer to all parameters in the sequence shown for a 
correct interpretation of parameter usage. 
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State — The state parameter determines the overall function of this 
master section (and transmitter and receiver sections) in the PCLll 
communications link as it relates to the TDM bus. The neutral state 
(SS.NEU) places the master section in an inactive state where the unit 
will send and receive messages in a normal manner, but the master 
section cannot control transmitter timeslice allocation on the TDM 
bus. The master state (SS.MAS) designates this unit as TDM bus 
master, enabling control of transmitter unit timeslice allotments on 
the TDM bus; only one master section on the TDM bus can be designated 
TDM bus master. 

Mode — The TDM bus master can allocate transmitter timeslices in one 
of two ways: auto address mode (MS.AUT) or address silo mode 
(MS. ADS). When operating in the auto address mode (MS.AUT), which is 
the default mode for the TDM bus master, equal timeslice allotments 
are given to each transmitter unit; transmitter unit addresses are 
sequentially put on the TDM bus in descending order, one address for 
each timeslice. When operating in the address silo mode, transmitter 
unit addresses are transmitted in a user-specified sequence, allowing 
up to 50% of the timeslices to be allocated to one transmitter unit, 
if desired. 

The actual sequence of transmitter timeslice allocations for the 
address silo mode is set up in the user's task data buffer referenced 
by the stadd parameter. Certain constraints must be observed when 
specifying this information, as follows: 

• Each entry in the buffer is a byte containing a transmitter 
unit address. 

• At least 20 entries, but not more than 50 entries, must be 
specified. If less than 20 entries are specified, the driver 
will repeat the entire sequence, as specified, in order to 
attain the required minimum of 20 addresses. If more than 50 
addresses are specified, no change in timeslice allocation 
will be effected and an lE.VER error status will be returned 
to the task. 

• Identical transmitter addresses in either adjacent bytes or in 
first and last bytes should be avoided. When identical 
addresses appear in adjacent bytes in this manner, the driver 
inserts invalid "pad" transmitter addresses between identical 
addresses, effectively resulting in no-operation timeslices. 

• Transmitter addresses are decimal values ranging from 1 to 32 
(inclusive) which correspond to addresses implemented on the 
actual transmitter unit hardware. 

• The size parameter must correctly specify the number of 
address bytes contained in the buffer referenced by the stadd 
parameter . 



13.4 PCLll TRANSMITTER DRIVER STATUS RETURNS 

Table 13-3 lists PCLll transmitter driver return status codes and 
probable reasons. 
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Table 13-3 
PCLll Transmitter Driver Status Returns 



Code 



Reason 



IS. sue 



IS.TNC 



IE. BAD 



Successful completion 

The QIC function was successfully completed. If 
an 10. ATX function was completed, the second 
status word contains the number of bytes 
transferred; the message was not truncated. If 
an 10. SEC function was completed, the second 
status word contains the current contents of the 
master section's TMMR. 

Successful transfer but message truncated 

The 10. ATX function was completed, but the message 
was truncated by the receiver (the receiver buffer 
is too small) . The transmitter unit cannot 
determine how many words were actually received by 
the receiver unit; the second word of the I/O 
status block contains the length of the requested 
transfer, rather than the actual count of words 
successfully received in the receiver's buffer. 

Bad parameter specification 

A bad parameter specification was included in the 
10. ATX function, or an invalid state parameter or 
TDM bus timeslice allocation addressing mode was 
specified in the lO.STC function. 

This error status is also returned when an lO.STC 
function, issued to a TDM bus master operating in 
the address silo mode, refers to a data buffer 
containing an illegal series of transmitter 
addresses. An illegal series of addresses occurs 
when the number of entries specified for the 
timeslice allocation, plus the required number of 
pad addresses, either exceeds 50 or is less than 
0. 



lE.DNR 



Device not ready 

This error status return occurs in response to an 
10. ATX function when one of the following occurs: 



• Power failure in this CPU. 

• Device time-out (no response from the addressed 
receiver) . 

• Receiver was too slow in accepting or rejecting 
the transfer request. 

• The master section is inoperative. This error 
status is returned only after the number of 
retries specified in the 10. ATX function have 
been attempted without success. 

(continued on next page) 
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Table 13-3 (Cont.) 
PCLll Transmitter Driver Status Returns 



Code 



lE.VER 



lE.SPC 



lE.REJ 



lE.FLG 



lE.BBE 



IE. ABO 



lE.IFC 



Reason 



1 



Unrecoverable error 

The lO.STC function state setting could not be 
achieved because the task is not privileged or 
another device is TDM bus master. 

Illegal user buffer 

The buffer address specified in the lO.ATF 
function is outside of the issuing task's address 
space. 

Transfer rejected 

The data transfer request specified in the lO.ATX 
function was rejected by the addressed 
receiver — based on the source CPU identifier of 
the task issuing the request — and flagword. 

Event flag already specified 

An event flag was previously specified in an 
lO.STC function. 

Transmission error 

This error status is returned only after the 
number of retries specified in the 10. ATX function 
have been attempted without a successful 
transmission. (Cycle redundancy check errors or 
parity errors have been detected on each attempt.) 

Request terminated 

This status is returned when a pending I/O 
function has been aborted in response to an lO.KIL 
function being issued by the task. 

Illegal function 

A function code was specified in an I/O request 
that is illegal for PCLll transmitters. 



13.5 QIC MACRO — PCLll RECEIVER DRIVER FUNCTIONS 
13.5.1 Standard QIO Functions 

Table 13-4 lists the standard function of the QIO macro that is valid 
for the PCLll receiver driver. 
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Table 13-4 
Standard QIO Functions for PCLll Receivers 



Format 


Function 


QIOSC lO.KIL,... 


Cancel I/O request 



13.5.2 Device-Specific QIO Functions 

Table 13-5 lists the device-specific functions of the QIO macro that 
are valid for the PCLll receiver driver. 



Table 13-5 
Device-Specific QIO Functions for PCLll Receivers 



Format 


Function 


QIO$C 


lO.CRX,.. . ,<tef ,bufadd> 


CONNECT for reception 


QIO$C 


10. RTF,,.. 


Reject transfer 


QIO$C 


lO.ATF, . . . ,<stadd,size. 






retadd> 


Accept transfer 


QIO$C 


lO.DRX,... 


Disconnect from reception 



tef 



The number of a "trigger" event flag that will be set whenever a 
flagword is received over the TDM bus. 



bufadd 



The address of a 2-word buffer containing the transmitter id, 
trigger status, and the flagword. 



stadd 



The address of a data buffer to receive the message, 
address must occur on a word boundary (even address) . 



This 



size 



The data buffer size in bytes, 
even, positive value. 



The size specified must be an 



retadd 

PCLll receiver hardware registers will be returned upon 

successful completion of the function. Information describing 

the contents of these registers can be obtained by referring to 

the hardware documentation supplied with the PCLll option. 
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13.5.2.1 lO.CRX - Th 
receiver, if the rec 
When connected, this 
messages by means of 
(a local, common, or 
message is pending. 
TDM bus. When this h 
connected task is 
word transmitted by a 
the receiver unit. 



is I/O 


f unct 


eiver 
task 


is not 
is th 


the receiver 


group- 
It 


global 
is set 


appens, a si 

considered " 

transmitter 



ion connects the issuing 
currently connected to a 

e only task capable o 
on this CPU. The trigge 
event flag) informs the 
when a flagword is recei 

gnificant event is declar 

triggered." The flagword 
when attempting to send 



task to the 


nother task. 


f receiving 


r event flag 


task when a 


ved over the 


ed and the 


is the first 


a message to 



The bufadd parameter must be included in this I/O function to specify 
the address of a 2-word block, as follows: 



id 



sts 



f lagwd 



sts 



id 



The current trigger status. 



The identification code of the transmitter attempting to send the 
message. 



f lagwd 



The flagword transmitted to the connected receiver, 



Based on the information contained in the flagword and the 

identification code of the transmitter unit, the task can accept or 

reject the transfer. (Two I/O functions are provided 

purpose; see Sections 13.5.2.2 and 13.5.2.3.) 

respond to the transmitter's request within approximately 1.5 seconds; 

otherwise, an lE.DNR error status is returned to the task attempting 

the transmission. 



for this 
The receiver must 



13.5.2.2 10. RTF - This function informs the transmitter device that 
the message is being rejected by the receiver. Any attempt to issue 
this I/O function when the trigger event flag is not set will be 
ignored, and an lE.NTR error status will be returned to the task. 



13.5.2.3 lO.ATF - This function informs the transmitter device that 
the message is being accepted. Parameters specify both the data 
buffer into which the received data will be transferred, and the 
6-word buffer that will receive the contents of the receiver section 
hardware registers upon successfully completing the function. 

Unlike the 10. RTF function, the lO.ATF function can be issued before 
the task is triggered. When this is done, the lO.ATF function is 
queued for reception of any flagword. When the flagword is received, 
the receiver driver immediately executes the lO.ATF function; the 
connected task is not triggered and the flagword is not made available 
to the task. This approach is useful when it is not necessary to 
examine flagwords or to accept messages based on the source. 
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13.5.2.4 lO.DRX - This function is issued by a task to disconnect the 
receiver for use by other tasks. 



13.6 PCLll RECEIVER DRIVER STATUS RETURNS 

Table 13-6 lists PCLll receiver driver return status codes and 
probable reasons. 



Table 13-6 
PCLll Receiver Driver Status Returns 



Code 



Reason 



IS. sue 



IS.TNC 



IE. BAD 



lE.DNR 



Successful completion 



The I/O function or t 
successfully comple 
returned upon complet 
the high-order byte 
status block contains 
the transmitter dev 
The second word of th 
the number of bytes 
When this status is r 
lO.CRX function, and 
I/O status block cont 
the task to accept 
Section 13.5.2.1) . 



riggering o 
ted. When 
ion of the 
of the firs 
the identif 
ice that s 
e I/O status 
transferred 
eturned as 
the task bei 
ains informa 
or reject 



f the 

this s 
lO.ATF 
t word i 
ication 
ent the 
block 
over the 
a resul 
ng trigg 
tion tha 

the mes 



task was 

tatus is 

function, 

n the I/O 

code of 

flagword. 

contains 

TDM bus . 

t of an 

ered, the 

t enables 

sage (see 



Successful transfer but message truncated 

This I/O status is returned when the message is 
terminated because the receiver task message 
buffer specified in the lO.ATF function is too 
small to contain the message being received. The 
second word of the I/O status word contains the 
number of bytes successfully transferred. 

Bad parameter specification 

A bad parameter specification was included in the 
requested function. 

Device not ready 

This error status return occurs in response to an 
10. RTF or lO.ATF function when one of the 
following occurs: 

• Power failure in this CPU. 

• Device time-out (no response from addressed 
receiver) . 

• Receiver was too slow in accepting or rejecting 

• The master section is inoperative. 



(continued on next page) 
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Table 13-6 (Cont.) 
PCLll Receiver Driver Status Returns 



Code 



Reason 



lE.SPC 



lE.DNA 



Illegal user buffer 

The buffer address specified in the lO.ATF 
function is outside of the issuing task's address 
space. 

Task not connected for reception 

The requested function cannot be executed because 
the task is not connected to the receiver. 



IE. DAG 



Data overrun 



lE.DAA 



lE.NTR 



lE.BBE 



This I/O status code is returned when the task is 
triggered, but the previous transfer request has 
neither been accepted nor rejected. When the task 
issues an 10. RTF or lO.ATF function, it will apply 
to the new (most recent) flagword; the previous 
request is ignored. 

Device already connected for reception 

This I/O status code is returned in response to 
the lO.CRX function when the receiver is already 
connected to this task or any other task. No 
operation is performed. 

Task not triggered 

This I/O status code is returned when a task 
attempts to issue an 10. RTF function prior to the 
task being triggered. 

Transmission error 



IE. ABO 



lE.FHE 



This error status is returned when an lO.ATF 
function is in progress and a cycle redundancy 
check error or parity error has been detected. 

Request terminated 

This status is returned when a pending I/O 
function has been aborted in response to an lO.KIL 
function being issued by the task. 

Fatal hardware error 



lE.IFC 



The requested function cannot be executed because 
of a hardware failure. 

Illegal function 

A function code was specified in an I/O request 
that is illegal for PCLll transmitters. 
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CHAPTER 14 
ANALOG-TO-DIGITAL CONVERTER DRIVERS 



14.1 INTRODUCTION 

The AFCll and ADOl-D analog-to-digital (A/D) converters are used to 
acquire industrial and laboratory analog data. (AFCll and ADOl-D 
driver support is not provided on RSX-llM-PLUS systems.) Although each 
has its own driver, programming for both is quite similar and both are 
multichannel, programmable gain devices. The ADOl-D should not be 
confused with the ADUOl, a UDC module, which is described in Chapter 
15. Table 14-1 compares the AFCll and the ADOl-D briefly, and 
subsequent sections describe these devices in greater detail. 



Table 14-1 
Standard Analog-to-Digital Converters 





AFCll 


ADOl-D 


Maximum Sampling Rate (Points 
per Second) 

Number of Bits 

Maximum Number of Analog Channels 
That Can Be Multiplexed 


200 (20 per single) 
channel 

13 or 14 

1024 


Approximately 
10,000 

10 or 11 

64 



14.1.1 AFCll Analog-to-Digital Converter 

The AFCll is a differential analog input subsystem for industrial 
data-acquisition and control systems. It multiplexes signals, selects 
gain, and performs a 13- or 14-bit analog-to-digital conversion under 
program control. With the use of appropriate signal-conditioning 
modules, the system can intermix and accept low-level, high-level, and 
current inputs, with a high degree of noise immunity. 



14.1.2 ADOl-D Analog-to-Digital Converter 

The ADOl-D is an extremely fast analog data-acquisition system. It 
multiplexes signals, selects gain, and performs a 10- or 11-bit 
analog-to-digital conversion under program control. The ADOl-D is 

*-i/Nii-T«Qni\y iii-iT 1-^^ lav Vmi4- ^r\ /^r\i- ^ ^\r\ ^1 a ^ r^ ir\ Ki-I- ■Fai^'iTit-af-^e ^^^ or» 1 A r 

operation. 
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14.2 GET LUN INFORMATION MACRO 

If a GET LUN INFORMATION system directive is issued for a LUN 
associated with an analog-to-digital converter, word 2 (the first 
characteristics word) contains all Os, words 3 and 4 are undefined, 
and word 5 is not significant, since there is no concept of a default 
buffer size for analog-to-digital converters. 



14.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
analog-to-digital converter drivers. 



14.3.1 Standard QIO Function 

The standard function that is valid for analog-to-digital converters 
is shown in Table 14-2. 



Table 14-2 
Standard QIO Function for the A/D Converters 



Format 


Function 


QIO$C lO.KIL,... 


Cancel I/O requests 



Since all requests are processed within a small amount of time, no 
in-progress request is ever canceled. This function simply cancels 
all queued requests. 



14.3.2 Device-Specific QIO Function 

The device-specific function of the QIO macro that is valid for 
analog-to-digital converters is shown in Table 14-3. 



Table 14-3 
Device-Specific QIO Function for the A/D Converters 



Format 


Function 


QIO$C lO.RBC, . . . ,<stadd,size,stcnta> 


INITIATE multiple A/D 
conversions 



stadd 



The starting address of the data buffer (must be on a word 
boundary) . 
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size 



The control buffer size in bytes (must be even and greater than 
0) ; the data buffer is the same size. 



stcnta 



The starting address of the control buffer (must be on a word 
boundary) ; each control buffer word must be constructed as shown 
in Table 14-4. 



Table 14-4 
A/D Conversion Control Word 



Bits 


Meaning 


AFCll 


ADOl-D 


0-11 


Channel number 




Range: 0-1023 


Range: 0-63 


12-15 


Gain value for th] 
sample, expressed 
a bit pattern as 
follows: 

15 14 13 


-S 

as 
12 


Gain: 


Gain: 












1 


1 









1 


2 


2 






1 





illegal 


4 






1 


1 


illegal 


8 






10 





10 


illegal 






10 


1 


20 


illegal 






oil 





illegal 


illegal 






oil 


1 


illegal 


illegal 






10 





50 


illegal 






10 


1 


100 


illegal 






1 1 





illegal 


illegal 






1 1 


1 


illegal 


illegal 






1 1 





200 


illegal 






110 


1 


1000 


illegal 






111 





illegal 


illegal 






111 


1 


illegal 


illegal 





14.4 FORTRAN INTERFACE 

A collection of FORTRAN-callable subroutines provide FORTRAN programs 
access to the AFCll and the ADOl-D. These are described in this 
section. All are reentrant and may be placed in a resident library. 



14.4.1 Synchronous and Asynchronous Process Control I/O 

The ISA standard provides for synchronous and asynchronous I/O. 
Synchronous I/O is indicated by appending a "W" to the name of the 
subroutine (for example, AISQ/AISQW) . The synchronous call suspends 
task execution until the I/O operation is complete. If the 
asynchronous form is used, execution continues and the calling program 
must periodically test the status word for completion. 
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14.4.2 The isb Status Array 

The isb (I/O status block) parameter is a 2-word integer array that 
contains the status of the FORTRAN call, in accordance with ISA 
convention. This array serves two purposes: 

1. It is the 2-word I/O status block to which the driver returns 
a status code on completion of an I/O operation. 

2. The first word of isb receives a status code from the FORTRAN 
interface in ISA-compatible format, with the exception of the 
I/O pending condition, which is indicated by a status of 0. 
The ISA standard code for this condition is +2. 

The meaning of the contents of isb varies, depending on the FORTRAN 
call that has been executed; but Table 14-5 lists certain general 
principles that apply. The section describing each subroutine 
provides further details. 



Table 14-5 
Contents of First Word of isb 



Contents 


Meaning 


isb(l) = 
isb(l) = 1 
isb{l) = 3 

3 < isb{l) < 300 
isb(l) > 300 


Operation pending; I/O in progress 

Successful completion 

Interface subroutine unable to 
generate QIO directive, or number of 
samples is 

QIO directive rejected and actual 
error code = -(isb(l) - 3) 

Driver rejected request and actual 
error code = -(isb(l) - 300) 



Unless otherwise specified, the value of isb{2) is the value returned 
by the driver to the second word of the I/O status block. 

FORTRAN interface subroutines depend on asynchronous system traps to 
set their status. Thus, if the trap mechanism is disabled, proper 
status cannot be set. 



14.4.3 FORTRAN Subroutine Summary 

Table 14-6 lists the FORTRAN interface subroutines supported for the 
AFCll and ADOl-D under RSX-llM. 
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Table 14-5 
FORTRAN Interface Subroutines for the AFCll and ADOl-D 



Subroutine 


Function 


AIRD/AIRDW 


Perforin input of analog data in random 




s quence 


AISQ/AISQW 


Read a series of sequential analog 




input channels 


ASADLN 


Assign a LUN to the ADOl-D 


ASAFLN 


Assign a LUN to the AFCll 



The following subsections briefly describe the function and format of 
each FORTRAN subroutine call. Note the use of ASADLN and ASAFLN to 
assign a default logical unit number. 



14.4.4 AIRD/AIRDW: Performing Input of Analog Data in Random Sequence 

The ISA standard AIRD/AIRDW FORTRAN subroutines input analog data in 
random sequence. These calls are issued as follows: 



CALL 



AIRD \ 
. AIRDW ) 



(inm,icont,idata, [isb] , [lun] ) 



inm 



The number of analog input channels. 



icont 



An integer array containing terminal connection data-channel 
number (right-justified in bits 0-11) and gain (bits 12-15), as 
shown in Table 14-4. 



idata 



isb 



An integer array to receive the converted values. 



A 2-word integer array to which the subroutine status is 
returned. 



lun 



The logical unit number. 
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The isb array has the standard meaning defined in Section 14.4.2. If 
inm = 0, then isb(l) = 3. The contents of idata are undefined if an 
error occurs. 



14.4.5 AISQ/AISQW: Reading Sequential Analog Input Channels 

The ISA standard AISQ/AISQW FORTRAN subroutines read a series of 
sequential analog input channels. These calls are issued as follows: 

(AISQ ) 
CALL ^ > (inm,icont,idata,[isb] , [lun] ) 
(aisqw ' 



inm 

The number of analog input channels. 



icont 



An integer array containing terminal connection data-channel 
number (right- justified in bits 0-11) and gain (bits 12-15), as 
shown in Table 14-4. 



idata 

An integer array to receive the converted values. 



isb 



lun 



A 2-word integer array to which the subroutine status is 
returned. 



The logical unit number. 



For sequential analog input, channel number is computed in steps of 
one, beginning with the value specified in the first element of icont. 
The channel number field is ignored in all other elements of the 
array. 

The gain used for each conversion is taken from the respective element 
in icont. Thus, even though the channel number is ignored in all but 
the first element of icont, the gain must be specified for each 
conversion to be performed. 

The isb array has the standard meaning defined in Section 14.4.2. If 
inm = 0, then isb(l) = 3. The contents of idata are undefined if an 
error occurs. 
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14.4.6 ASADLN: Assigning a LUN to the ADOl-D 

The ASADLN FORTRAN subroutine assigns the specified LUN to the ADOl-D 
and defines it as the default logical unit number to be used whenever 
a LUN specification is omitted from an AIRD(W) /AISQ(W) subroutine 
call. It is issued as follows: 

CALL ASADLN (lun , [ isw] , [ iun] ) 



lun 



isw 



The logical unit number to be assigned to the ADOl-D and defined 
as the default unit. 



An integer variable to which the result of the ASSIGN LUN system 
directive is returned. 



lun 

The unit number to be assigned. If unspecified, a value of is 
assumed. 

Only the LUN specified in the last call to ASADLN or ASAFLN is defined 
as the default unit. 



14.4.7 ASAFLN: Assigning a LUN to the AFCll 

The ASAFLN FORTRAN subroutine assigns the specified LUN to the AFCll 
and defines it as the default logical unit number to be used whenever 
a LUN specification is omitted from an AIRD(W) /AISQ(W) subroutine 
call. It is issued as follows: 

CALL ASAFLN (lun , [ isw] , [ iun] ) 



lun 



ISW 



The logical unit number to be assigned to AFCll and defined as 
the default unit. 



An integer variable to which the status from the ASSIGN LUN 
system directive is returned. 



iun 

The unit number to be assigned. If unspecified, a value of is 
assumed . 

Only the LUN specified in the last call to ASAFLN or ASADLN is defined 
as the default unit. 



14-7 



ANALOG-TO-DIGITAL CONVERTER DRIVERS 



14.5 STATUS RETURNS 

The error and status conditions listed in Table 14-7 are returned by 
the analog-to-digital converter drivers described in this chapter. 



Table 14-7 
A/D Converter Status Returns 



Code 



IS. sue 



IS.PND 



IE. ABO 



IE. BAD 



IE. BYT 



lE.DNR 



Reason 



Successful completion 

The operation specified in the QIO directive was 
completed successfully. The second word of the I/O 
status block can be examined to determine the number 
of A/D conversions performed. 

I/O request pending 

The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 

Operation aborted 

The specified I/O operation was canceled with lO.KIL 
while still in the I/O queue. 

Bad parameter 

An illegal specification was supplied for one or more 
of the device-dependent QIO parameters (words 6-11) , 
For the analog-to-digital converters, this code 
indicates that a bad channel number or gain code was 
specified in the control buffer. 

Byte-aligned buffer specified 

Byte alignment was specified for a data or control 
buffer, but only word alignment is legal for 
analog-to-digital converters. Alternatively, the 
length of the data and control buffer is not an even 
number of bytes. 

Device not ready 

The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. For the AFCll, this code is returned if 
an interrupt time-out occurred or the power failed. 
In the case of the ADOl-D, which is not operated in 
interrupt mode, this code indicates a software 
time-out occurred (that is, a conversion did not 
complete within 30 microseconds) . 



(continued on next page) 
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Table 14-7 (Cont.) 
A/D Converter Status Returns 



Code 



lE.IFC 



lE.OFL 



lE.SPC 



Reason 



Illegal function 

A function code was specified in an I/O request that 
is illegal for analog-to-digital converters. 

Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. 

Illegal address space 

The data or control buffer specified for a conversion 
request was partially or totally outside the address 
space of the issuing task. Alternately, a byte count 
of was specified. 



FORTRAN interface values for these subroutines are presented in 
Section 14.5.1. 



14.5.1 FORTRAN Interface Values 

The values listed in Table 14-8 are returned in FORTRAN subroutine 
calls. 



Table 14-8 
FORTRAN Interface Values 



Status Return 


FORTRAN Value 


IS. sue 


+01 


IS.PND 


+00 


IE. ABO 


+315 


lE.ADP 


+101 


IE. BAD 


+301 


IE. BYT 


+319 


lE.DAO 


+313 


lE.DNR 


+ 303 


lE.IEF 


+100 


lE.IFC 


+302 


lE.ILU 


+99 


IE. NOD 


+323 


lE.ONP 


+305 


lE.PRI 


+316 


lE.RSU 


+317 


lE.SDP 


+102 


lE.SPC 


+306 


lE.ULN 


+08 


lE.UPN 


+04 
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14.6 FUNCTIONAL CAPABILITIES 

The AFCll and ADOl-D operate only in multisaraple mode, because the 
user can simulate single-sample mode by simply specifying one sample. 
Multisample mode permits many channels to be sampled at approximately 
the same time without requiring the user to queue multiple I/O 
requests. 

The maximum number of channels in the configuration is specified at 
system-generation time. This value is stored in the respective AFCll 
and ADOl-D unit control blocks. 



14.6.1 Control and Data Buffers 

The user must define two buffers of equal size: the control buffer 
and the data buffer. The former contains the control words needed to 
perform one A/D conversion per channel specified. Each control word 
indicates the channel to be sampled and the gain to be applied (see 
Table 14-4) . 

The data buffer receives the results of the conversions. Each result 
is placed in the data buffer location that corresponds to the control 
word that specified it. 



14.7 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the analog-to-digital converter 
drivers described in this chapter. 



14.7.1 Use of A/D Gain Ranges 

Note that the A/D gain ranges overlap. The key to successful use of 
the A/D converters is to change to a higher gain whenever a full-scale 
reading is imminent, and to change to a lower gain whenever the last 
A/D value recorded was less than half of full scale. This method 
maintains maximum resolution while avoiding saturation. 



14.7.2 Identical Channel Numbers on the AFCll 

When requesting sampling of more than one channel, the user should not 
specify multiple sampling of a single channel without _ lOor more 
intervening samples on other channels. This ensures 50 milliseconds 
between samples on a single channel. If sampling occurs more often 
than this on a single channel, partial results are returned (see 
Section 14.7. 3) . 
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14.7.3 AFCll Sampling Rate 

Although the AFCll can sample a maximum of 200 points per second, a 
single channel can only be sampled at 20 points per second. Because 
the channel capacitor needs 50 milliseconds to recharge after each 
conversion, more frequent sampling may result in partial readings. If 
this occurs, the user will receive no indication that information is 
being lost. To ensure that information is not lost on any one 
channel, the user should sample approximately 10 other channels before 
returning to the first one. 



14.7.4 Restricting the Number of ADOl-D Conversions 

The ADOl-D is an extremely fast device, providing a 25-microsecond 
conversion rate, and is driven programmably to minimize system 
overhead. However, an excessive number of conversions in a single 
request essentially locks out the rest of the system, because the 
driver does not return control to the system until it has finished all 
the specified conversions. No other task can run, although interrupts 
can still occur and are processed. 
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UNIVERSAL DIGITAL CONTROLLER DRIVER 



15.1 INTRODUCTION 

The UDCll is a digital input/output system for industrial and process 
control applications. It interrogates and/or drives up to 252 
directly addressable digital sense and/or control modules. The UDCll 
operates under program control as a high-level digital multiplexer, 
interrogating digital inputs and driving digital outputs. (UDCll 
driver support is not provided on RSX-llM-PLUS systems.) 

The UDC driver will support either the UDCll or ICSll subsystem. The 
ICSll (Industrial Control Subsystem) operates as an input/output 
device that is functionally similar to the UDCll. A maximum of 16 I/O 
modules can be placed in one ICSll subsystem; up to 12 ICSlls can be 
interfaced to one computer system. The ICSll subsystem is also 
supported by the ICS/ICR-11 driver described in Chapter 18. The 
reader should consult that chapter for a comparison of driver 
features. 

While performing analog-to-digital conversions, the UDCll driver can 
handle other functions, such as contact or timer interrupts or 
latching output. These functions are performed immediately, without 
requiring any in-progress analog-to-digital conversions to first be 
completed. 

Unlike other RSX-llM I/O device drivers, the UDCll driver is neither a 
multicontroller nor a multiunit driver. 



15.1.1 Creating the UDCll Driver 

Each installation must assemble the driver source module with a prefix 
file that defines the particular hardware configuration. The prefix 
file is created during system generation according to the user's 
response to questions relating to the UDCll. This file is named 
RSXMC.MAC and includes symbolic definitions of the UDCll 
configuration. These definitions encode the relative module number 
and the number of modules for each generic type specified in the 
system generation dialog. The encoding has the following format: 

8 8 



number of modules 



starting module number 
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One or more of the following symbols is generated: 

Symbol Module Type 

U$$ADM Analog input 

U$$AOM Analog output 

U$$CIM Contact interrupt 

U$$CSM Contact sense input 

U$$LTM Latching digital output 

U$$SSM Single-shot digital output 

U$$TIM Timer (I/O counter) 

Note that all modules of a given type must be installed together in 
sequential slots. 



15.1.2 Accessing UDCll Modules 

RSX-llM provides two methods of accessing the UDCll: 

1. A QIO macro call issued to the driver 

2. Restricted direct access by any task to I/O page registers 
dedicated to the UDCll 

The first method, access through the driver, is required to service 
interrupting modules and to set and record the state of latching 
digital output modules. 

The second method, direct access, is a high-speed, low-overhead way to 
service noninterrupting modules. The following functions may be 
performed in this manner: 

• Analog output 

• Contact sense input 

• Single-shot digital output 

• Read a contact interrupt module 

• Read a timer module 



15.1.2.1 Driver Services - The driver services the following types of 
modules : 

• Contact interrupt 

• Timer (I/O counter) 

• Analog input 

• Latching digital output 

Contact and timer interrupts need not be serviced by a single task. 
One task may be connected to contact interrupts, and another to timer 
interrupts. A nonprivileged task can connect to either or both of 
these classes by providing a circular buffer to receive interrupt 
information and an event flag to allow triggering of the task whenever 
a buffer entry is made. 
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15.1.2.2 Direct Access - A global common block within the I/O page 
provides restricted direct access to the UDCll device registers. In a 
mapped system, the length of the block is set to prevent access to 
other device registers. In an unmapped system, the use of the common 
block is optional, unless ISA FORTRAN calls are used. The ISA 
routines refer symbolically to the UCDll registers, and thus require 
the use of global common. Section 15.4 explains direct access more 
fully. 



15.2 GET LUN INFORMATION MACRO 

If a GET LUN INFORMATION system directive is issued for a LUN 
associated with the UDCll, word 2 (the first characteristics word) 
contains all zeros, words 3 and 4 are undefined, and word 5 is not 
significant, since there is no concept of a default buffer size for 
universal digital controllers. 



15.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
the UDCll driver. In issuing them, note the numbering conventions 
described in 15.7.2. 



15.3.1 Standard QIO Function 

The standard function that is valid for the UDCll is shown in Table 
15-1. 



Table 15-1 
Standard QIO Function for the UDCll 



Format 


Function 


QIO$C lO.KIL,... 


Cancel I/O requests 



lO.KIL cancels all queued requests and disconnects all interrupt 
connections, but does not stop any I/O that is currently in progress. 



15.3.2 Device-Specific QIO Functions 

Table 15-2 summarizes device-specific QIO functions that are supported 
for the UDC12. 
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Table 15-2 
Device-Specific QIC Functions for the UDCll 



Format 


Function 


QIO$C 


lO.CCI, 


. . . ,<stadd ,sizb,tevf > 


CONNECT a buffer to contact 
interrupts 


QIOSC 


lO.CTI, 


. . . ,<stadd,sizb,tevf ,arv> 


CONNECT a buffer to timer 
interrupts 


QIO$C 


lO.DCI, 


• • • 


Disconnect a buffer from 
contact interrupts 


QIO$C 


10. DTI, 


* • • 


Disconnect a buffer from timer 
interrupts 


QIO$C 


lO.ITI, 


. . . ,<mn,ic> 


INITIALIZE a timer 


QIOSC 


lO.MLO, 


. ..,<opn,pp,dp> 


OPEN or close latching digital 
output points 


QIO$C 


lO.RBC, 


. . . ,<stadd,size,stcnta> 


INITIATE multiple A/D 
conversions 



stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



sizb 



The data buffer size in bytes (must be even and large enough to 
include a 2-word buffer header plus one data entry; the buffer 
may cross a 4K boundary) . 



tevf 



arv 



mn 



ic 



opn 



The trigger event flag number. 



The starting address of the table of initial/reset values (must 
be on a word boundary) . 



The module number, 



The initial count. 



The first latching digital output point number, which must be on 
a module boundary (evenly divisible by 16) . 
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PP 



dp 



Size 



The 16-bit mask. 



The data pattern. 



The control buffer size in bytes (must be even and greater than 
0); the data buffer is the same size. 



stcnta 



The starting address of the control buffer (must be on a word 
boundary) ; each control buffer word must be constructed as shown 
in Table 15-3. 



The following sections describe the functions listed in Table 15-2. 



Table 15-3 
A/D Conversion Control Word 



Bits 



0-11 
12-15 



Meaning 



Channel number 

Gain value for this 
sample, expressed as 
a bit pattern as 
follows : 

15 14 13 12 
























1 








1 











1 


1 





1 











1 





1 





1 


1 








1 


1 


1 





















1 







1 










1 


1 




1 










1 





1 




1 


1 







1 


1 


1 



ADUOl 



Range: 0-4095 
Gain: 



1 
2 
Illegal 
Illegal 
10 
20 
Illegal 
Illegal 
50 
100 
Illegal 
Illegal 

200 
1000 
Illegal 
Illegal 
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15.3.2.1 Contact Interrupt Digital Input (W733 Modules) - Digital 
input and change of state information from contact interrupt modules 
is reported in a requester-provided circular buffer. The buffer 
consists of a 2-word header, followed by a data area in the following 

format : 



1 


driver index 


2 


user index 


3 


entry 


4 


entry 


• 


• 


• 


• 


• 


• 



Whenever a change of state occurs in one or more contact points, an 
interrupt is generated. The UDCll driver gains control, determines 
whether the change of state is of interest (that is, a contact closure 
and point closing . (PCL) is set on the module) , and then optionally 
makes an entry in the data area of the buffer, updates the index 
words, and sets the trigger event flag of the connected task. 

Each entry consists of five words in the following format: 

Word Contents 

Entry existence indicator 

1 Change-of-state (COS) indicator 

2 Module data (current point values) 

3 Module number (interrupting module) 

4 Generic code (interrupting module) 

The driver enters data in the location currently indicated by the 
driver index. This pointer can be considered as a FORTRAN index into 
the buffer; that is, the first location of the buffer is associated 
with the index 1. The beginning of the data area is the location of 
the first entry (index 3). Entries are made in a circular fashion, 
starting at the beginning of the data area, filling in order of 
increasing memory address to the end of the data area, and then 
wrapping around from the end to the beginning of the data area. 

It is expected that the connected task will maintain its own pointer 
(the user index) to the location in the buffer where it is next to 
retrieve contact interrupt data. When a task is triggered by the 
driver, it should process data in the buffer starting at the location 
indicated by its pointer and continuing in a circular fashion until 
the two pointers are equal or a zero entry existence indicator is 
encountered. Equality of pointers means that the connected task has 
retrieved all the contact interrupt information that the driver has 
entered into the buffer. 

The entry existence indicator is set to nonzero when a buffer entry is 
made. When a requester has removed or processed an entry, he must 
clear the existence indicator in order to free the buffer entry 
position. 
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If data input occurs in a burst sufficient to overrun the buffer, data 
is discarded and a count of data overruns is incremented. The nonzero 
entry existence indicator also serves as an overrun indicator. A 
positive value (+1) indicates no overruns between entries; a negative 
value is the two's complement of the number of times data have been 
discarded between entries. 

The module number indicates a module on which a change of state in the 
direction of interest has been recognized for one or more discrete 
points. The direction of the change may be from to 1 or 1 to 0, 
depending on the PCL (point closing) and POP (point opening) module 
jumpers. The change of state (COS) indicator specifies which point or 
points of the module have changed state. 

The bit position of an on-bit in the COS indicator provides the 
low-order bits (3-0) of a point number and the module number provides 
the high-order bits (15-4). The module data indicates the logical 
value (polarity) of each point in the module at the time of the 
interrupt. 

Contact interrupt data can be reported to only one task. The 
functions lO.CCI and lO.DCI in Table 15-2 are provided to enable a 
task to connect and disconnect from contact interrupts. If the 
connection is successful, the second word of the I/O status block 
contains the number of words passed per interrupt in the low-order 
byte and the initial FORTRAN index to the beginning of the data area 
in the high-order byte. 

NOTE 

The size of the data area must be a 
multiple of the entry size. 



15.3.2.2 Timer (W734 I/O Counter Modules) - A timer (I/O counter) 
module is a clock that is initialized (loaded), counts up or down, and 
then causes an interrupt. The UDCll driver treats such modules in a 
way similar to that in which it handles contact interrupts. The 
requester provides a circular buffer similar to that for contact 
interrupts. Each entry consists of four words in the following 
format: 

Word Contents 

Entry existence indicator 

1 Module data (current value) 

2 Module number (interrupting module) 

3 Generic code (interrupting module) 
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The lO.CTI function in Table 15-2 enables a task to connect to timer 
interrupts. The table of initial/reset values is used to initially 
load the timers and to reload them on interrupt (overflow) . The table 
contains one word for each timer module. The contents of the first 
word are used to load the first module, and so forth. If a timer has 
a nonzero value when it interrupts, it is not reloaded, so that 
self-clocking modules and modules that interrupt on half count can 
continue counting from the initial value. 

The 10. DTI function in Table 15-2 disconnects a task from timer 
interrupts, and the lO.ITI function provides the capability of 
initializing a single timer. Requests to initialize a counter are 
valid only if the issuing task has connected a buffer for receiving 
counter interrupts. 

NOTE 

The size of the data area must be a 
multiple of the entry size. 



15.3.2.3 Latching Digital Output (M685, M803, and M805 Modules) - 
Each module has 16 latching digital output points. The lO.MLO 
function in Table 15-2 opens or closes a set of up to 16 points. Bit 
n of the mask and data pattern corresponds to the point opn + n. If a 
bit in the mask is set, the corresponding point is opened or closed, 
depending on whether the corresponding bit in the data pattern is 
clear or set. If a bit in the mask is clear, the corresponding point 
remains unaltered. 



15.3.2.4 Analog-to-Digital Converter (ADUOl Module) - Each ADUOl 
module has eight analog input channels. The lO.RBC function in Table 
15-2 initiates A/D conversions on multiple ADUOl input channels. 
Restrictions on maximum sampling rates are the same as those defined 
for the AFCll in Chapter 14. 

The converted analog value is returned as 12 bits, left-justified, in 
a 16-bit word with the low-order 4 bits set to 0. 



15.3.2.5 ICSll Analog-to-Digital Converter (lAD-IA Module) - Each 
lAD-IA Module has eight analog input channels. The channel capacity 
may be expanded to 120 by the addition of IMX-IA multiplexers. Each 
multiplexer adds 16 input channels to the converter. Restrictions on 
maximum sampling rates are the same as those defined for the AFCll in 
Chapter 14. The lAD-IA module preempts eight module slots regardless 
of the number of IMX-IA multiplexers installed. 

For addressing purposes, each converter occupies a block of 120 
channels. Thus, A/D converter is addressed by referencing channels 
through 119; A/D converter 1 is addressed by referencing channels 
120 through 239, and so forth. When fewer than seven multiplexers are 
installed, not all addresses within the block are valid. 

The converted analog value is returned as 12 bits, left-justified, in 
a 16-bit word with the low-order 4 bits set to 0. 
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15.4 DIRECT ACCESS 

Section 15.1.2 describes UDCll functions that may be performed by 
referencing a module through its physical address in the I/O page. 
Under RSX-llM such access is accomplished by one of the following 
methods: 

1. A privileged task or any task running in an unmapped system 
has unrestricted access to the I/O page, and may therefore 
access each module by absolute address. 

2. Using the Task Builder, a task may link to a global common 
area whose physical address limits span a set of locations in 
the I/O page. This method applies to either a mapped or 
unmapped system. 

The latter method allows a task to be transported to any other system 
simply by relinking. Furthermore, in a mapped system the memory 
management hardware will abort all references to device registers 
outside the physical address limits of the common block. 

The operations required to implement each method may be summarized as 
follows: 

1. Unrestricted access to the I/O page 

a. An object module is created that defines the UDCll 
configuration through a list of absolute global addresses 
and addressing limits for each module type. 

b. The object module is included in the system library file. 

c. A task is created containing the appropriate global 
references. Such references are resolved when the task 
builder automatically searches the system library file. 

Steps a and b are executed once, during system generation (see the 
RSX-llM System Generation and Management Guide ) . Step c is performed 
each time a task is created that references the UDC12. 

2. Access to the I/O page through a Global Common Block 

a. An object module is created that defines the UDCll 
configuration through a list of relocatable global 
addresses and addressing limits for each module type. 

b. The object module is linked, using the Task Builder, to 
create an image of the Global Common block on disk. 

c. The SET command is used to define a common block that 
resides on the I/O page. 

d. The INSTALL MCR command is used to make the Global Common 
Block resident in memory. 

e. A task is created containing the appropriate global 
references. Such references are resolved by directing 
the Task Builder to link the task to the common block. 

Steps a through d are executed once, during system generation. Step e 
is performed each time a task is created that references the UDCll 
common block. The following paragraphs describe each step in detail. 
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15.4.1 Defining the UDCll Configuration 

The source module UDCOM.MAC,! when assembled with the proper prefix 
file, provides global definitions for the following parameters: 

• The starting address of each module type 

• The highest point number within a given module type 

• The highest module number within a given module type 

The last two parameters are absolute quantities that may be used to 
prevent a task from referencing a module that is nonexistent or out of 
1 imits. 

By means of conditional assembly, the list of addresses may be created 
as absolute symbols defining locations in the I/O page, or as symbols 
within a relocatable program section to be used when building and 
linking to the UDCll Global Common area. 



15.4.1.1 Assembly Procedure for UDCOM.MAC - UDCOM.MAC is assembled 
with the RSX-llM configuration parameters contained in the file 
RSXMC.MAC. 

To create relocatable module addresses, either the parameter U$$DCM or 
M$$MGE must be defined. M$$MGE will be included in RSXMC.MAC if 
memory management was specified when the system was generated. If 
not, the user should edit the file to include the following 
definition: 

U$$DCM=0 

The file may then be assembled using the MCR command: 

>MAC UDCOM , UDLST= [11,10] RSXMC , UDCOM 

This command invokes the MACRO-11 assembler, which processes the input 
files RSXMC.MAC and UDCOM.MAC to create UDCOM. OBJ and UDLST.LST. 

To create absolute module addresses, both U$$DCM and M$$MGE must be 
undefined. Edit RSXMC.MAC, if necessary, to remove definitions and 
then invoke the MACRO-11 assembler with the following MCR command: 

>MAC UDCDF,UDLST=[1 1,10] RSXMC, UDCOM 

In this sequence the files UDCDF.OBJ and UDLST.LST are created from 
the specified source modules. UDCDF.OBJ contains the module addresses 
in absolute form. 



15.4.1.2 Symbols Defined by UDCOM.MAC - This section lists the 
symbolic definitions created by UDCOM.MAC. 



1. This module resides on the RK05 cartridge of the RSX-llM RK 
distribution kit labeled EXECUTIVE SOURCE. For RP distribution kits, 
it resides on the RP image. The file is located under UIC [11,10]. 
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The following symbols define the absolute or relocatable address of 
the first module of a given type: 

Symbol Module Type 

$.ADM Analog input 

$-AOM Analog output 

$.CIM Contact interrupt 

$.CSM Contact sense input 

$.LTM Latching digital output 

S.SSM Single-shot digital output 

$.TIM Timer (I/O counter) 

The addresses in relocatable form are defined in a program section 
named UDCOM having the attributes: 

REL - relocatable 

OVR - overlaid 

D - data 

GBL - global scope 

Note that these attributes correspond to those attached to a named 
common block within a FORTRAN program. 

In either the absolute or relocatable case, individual modules are 
referenced by the corresponding symbolic address plus a relative 
module index. 

The following symbols define the highest digital point within a module 
type: 

Symbol Module Type 

P$.CIM Contact interrupt 

P$.CSM Contact sense input 

P$.LTM Latching digital output 

P^.SSM Single-shot digital output 

The highest point number is defined relative to the first point on the 
first module of a specific type. For example, if two contact 
interrupt modules are installed, the symbol P$.CIM will have an octal 
value of 37. 

The following symbols define the highest module number within a given 
module type. 

Symbol Module Type 

MS.ADM Analog input 

M$.AOM Analog output 

MS.CIM Contact interrupt 

M$.CSM Contact sense input 

M$.LTM Latching digital output 

M$.SSM Single-shot digital output 

M$.TIM Timer (I/O counter) 

The highest module number is defined relative to the first module of a 
given type. Thus, based on the previous example, M$.CIM will have a 
value of 1. 
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15,4.2 Including UDCl Symbolic Definitions in the System Object 
Module Library 

As described in Section 15.4, a task having unrestricted access to the 
I/O page may reference a UDCll module by absolute address. The object 
module UDCDF contains symbolic definitions of absolute module 
addresses and may be included in the System Object Module Library: 

SY: [1,1]SYSLIB,0LB 

The Task Builder automatically searches this file to resolve any 
undefined globals remaining after all input files have been processed. 

The following example illustrates the procedure for including the file 
UDCDF. OBJ in the library: 

>SET /UIC=[1,1] 

>LBR SySLIB/IN=[200,200]UDCDF 

The SET MCR command is issued to establish the current UIC as [1,1]. 
Next, the RSXllM Librarian is invoked and instructed, through the use 
of the /IN switch, to include the object module UDCDF. OBJ in the file 
SYSLIB.OLB. 



15.4.3 Referencing the UDCll through a Global Common Block 

The following sections define the procedure for creating a Global 
Common block in the I/O PAGE, making the block resident in memory, and 
creating a task that references UDCll modules within the block. 
Examples are given for both mapped and unmapped systems. 



15.4.3.1 Creating a Global Common Block - The following sequence 
illustrates the use of the object file UDCOM.OBJ to create a disk 
image of the global common area in a mapped system: 

>SET /UIC=[1,1] 

>TKB 

TKB>UDCOM/MM,LP:,SY:UDCOM/PI/-HD=r200,200]UDCOM 

TKB>/ 

ENTER OPTIONS: 

TKB>PAR=UDCOM: : 1000 

TKB>STACK=0 

TKB>/ 

In the above example, a current UIC of [1,1] is established and the 
Task Builder is initiated. The initial input line to the Task Builder 
specifies the following files: 

• A core image output file to be named UDCOM.TSK 

• A memory map output to the line printer 

• A symbol table file to be named UDCOM.STB 

All files reside on SY: under UIC [1,1]. The single input file 
UDCOM.OBJ, containing the UDCll address definitions as relocatable 
values, constitutes the input. 
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The switches specified for the output files convey the following 
information to the Task Builder: 

/MM indicates that the core image of the common block will 
reside on a system with Memory Management. 

/PI indicates that the core image is position independent; 

that is, the virtual address of the common block may 

appear on any 4K boundary within a task's address 
space. 

/-HD indicates that the core image will not contain a 
header. A header is only required for a core image 
file that is to be installed and executed as a task. 

The names of the partition, task file, and symbol-table files must 
agree. 

The STACK option must be used to eliminate the stack space. 

The following sequence illustrates the corresponding procedure for an 
unmapped system: 

>SET /UIC=[1,1] 

>TKB 

TKB>UDCOM/-MM,LP: , SY: UDCOM/PI/-HD= [2 00 , 200] UDCOM 

TKB>/ 

ENTER OPTIONS: 

TKB>STACK=0 

TKB>PAR=UDCOM: 171000 : 1000 

TKB>/ 

Again the task builder is requested to produce a core image and symbol 
table file under the UIC [1,1], and a map file on the line printer 
from the input file UDCOM. OBJ. The output file switches convey the 
following information: 

/-MM indicates that the core image of the common block will 
reside on an unmapped system. 

/PI Indicates that the core image is position independent. 
In an unmapped system, the core image is fixed in the 
same address space for all tasks; however, the global 
symbols defined in the symbol table file retain the 
relocatable attribute. 

/-HD indicates that a core image without a header is to be 
created . 

The PAR option specifies the base and length of the common area to 

coincide with the standard UDCll addresses in the I/O page. All 

references to the common block by tasks will be resolved within this 
region. 



15.4.3.2 Making the Common Block Resident - The following SET command 
creates a UDCll common block residing in the I/O page for a mapped 
system: 

>SET /MAIN=UDCOM:7710:10:DEV 
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The corresponding command in an unmapped system is: 

>SET /MAIN=UDCOM:1710:10:DEV 

The preceding sequence specifies the allocation of a common block in 
the I/O page whose physical address limits correspond to the UDCll 
standard locations. Note that the address bounds and length are 
defined in units of 32 words. 

The command 

>INS [1,1]UDC0M 

declares the common block resident in the system. 



15.4.3.3 Linking a Task to the UDCll Common Block - A task may access 
UDCll modules by linking to the common block as follows: 

TKB>TASK , LP : =TASK. OB J 

TKB>/ 

ENTER OPTIONS: 

TKB> COMMON=UDCOM:RW 

TKB>/ 

The above sequence is valid for either a mapped or unmapped system. 
In both cases the Task Builder will link the task to the common block 
by resolving references to the Global symbol definitions contained in 
UDCOM.STB. If memory management is present, the Executive will map 
the appropriate physical locations into the task's virtual addressing 
space when the task is made active. 



15.5 FORTRAN INTERFACE 

A collection of FORTRAN-callable subroutines provide FORTRAN programs 
access to the UDC12. These are described in this section. All are 
reentrant and may be placed in a resident library. 

Instead of using the FORTRAN-callable subroutines described in this 
section, a FORTRAN program may use the global common feature described 
in Section 15.4 to reference UDCll modules directly in the I/O page, 
as shown in the following example: 

C 

C UDCll GLOBAL COMMON 

C 

COMMON /UDCOM/ ICSM ( 10) , lAO (10) 
C 
C READ CONTACT SENSE MODULE 1 DIRECTLY 



C 



ICS=ICSM(1) 



Note that the position of each module type must correspond to the 
sequence in which storage is allocated in the common statements. 
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15.5.1 



Synchronous and Asynchronous Process Control I/O 



The ISA standard prov 
I/O. Synchronous I 
the subroutine (for e 
all UDCll I/O operat 
"W" form of the call 
meaning under RSX-1 
form is significant: 
until input is compl 
continues and the cal 
word for completion. 



ides for synchronous and asynchronous 
/O is indicated by appending a "W" to the 
xample, AO/AOW) . But due to the fact tha 
ions are performed immediately, in most c 
is retained only for compatibility and 
IM. In the case of A/D input, however. 
The synchronous call suspends task e 
ete. If the asynchronous form is used, e 
ling program must periodically test the 



process 

name of 

t nearly 

ases the 

has no 

the "W" 

xecution 

xecution 

status 



15.5.2 The isb Status Array 

The isb (I/O status block) parameter is a 2-word integer array that 
contains the status of the FORTRAN call, in accordance with ISA 
(Instrument Society of America) convention. This array serves two 
purposes: 

1. It is the 2-word I/O status block to which the driver returns 
an I/O status code on completion of an I/O operation. 

2. The first word of isb receives a status code from the FORTRAN 
interface in ISA-compatible format, with the exception of the 
I/O pending condition, which is indicated by a status of 0. 
The ISA standard code for this condition is +2. 

The meaning of the contents of isb varies, depending on the FORTRAN 
call that has been executed; but Table 15-4 lists certain general 
principles that apply. The section describing each subroutine qives 
more details. ^ 



In some cases, the values or states of points being read, pulsed, 
latched are returned to isb word 2. 



or 



FORTRAN interface subroutines for analog input depend on asynchronous 
system traps to set their status. Thus, if the trap mechanism is 
disabled, proper status cannot be set. 



Table 15-4 
Contents of First Word of isb 



Contents 



isb(l) = 
isb(l) = 1 
isb(l) = 3 

3 < isb(l) < 300 
isb(l) > 300 



Meaning 



Operation pending; I/O in progress 

Successful completion 

Interface subroutine unable to generate 
QIO directive or number of points 
requested is zero 

QIO directive rejected and actual error 
code = -(isb(l) - 3) 

Driver rejected request and actual 
error code = -(isb(l) - 3001 
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For direct access calls (indicated in Table 15-5 below), errors are 
detected and returned by the FORTRAN interface subroutine itself, 
rather than by the driver. Although the use of a 2-word status block 
is therefore unnecessary, these errors are returned in standard format 
to retain compatibility with functions called through QIO directives 
and handled by other drivers. Errors of this type that may be 
returned are: 



isb(l) = 3 



isb(l) = +321 



Number of points requested is 


Invalid UDCll module 



15.5.3 FORTRAN Subroutine Summary 

Table 15-5 lists the FORTRAN interface subroutines supported for the 
UDCll under RSX-llM. (D) indicates a direct access call, and the 
optional logical unit number for such a call may be specified to 
retain compatibility with RSX-llD; but this specification is ignored 
by RSX-llM. 

The following subsections briefly describe the function and format of 
each FORTRAN subroutine call. Note the use of ASUDLN to specify a 
default logical unit number. Also consider the numbering conventions 
described in 15.7.2. 

The following FORTRAN functions do not perform I/O directly, but 
facilitate conversions between BCD and binary. 

Convert four BCD digits to a binary number: 

IBIN = KBCD2B(IBCD) 
Convert a binary number to four BCD digits: 

IBCD = KB2BCD(IBIN) 



Table 15-5 
FORTRAN Interface Subroutines for the UDCll 



Subroutine 


Function 


AIRD/AIRDW 


Perform input of analog data in random 
sequence 


AISQ/AISQW 


Read a series of sequential analog input 
channels 


AO/AOW 


Perform analog output on several channels 
(D) 


ASUDLN 


Assign a LUN to the UDCll 


CTDI 


Connect a circular buffer to receive 
contact interrupt data 



(continued on next page) 
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Table 15-5 (Cont.) 
FORTRAN Interface Subroutines for the UDCll 



Subroutine 


Function 


CTTI 


Connect a circular buffer to receive 
timer interrupt data 


DFDI 


Disconnect a buffer from contact 
interrupts 


DFTI 


Disconnect a buffer from timer interrupts 


DI/DIW 


Read several 16-point contact sense 
fields (D) 


DOL/DOLW 


Latch or unlatch several 16-point fields 


DOM/DOMW 


Pulse several 16-point fields (D) 


RCIPT 


Read the state of a single contact 
interrupt point (D) 


RDCS 


Read the contents of a contact interrupt 
circular buffer, returning data on only 
those points that have changed state 


RDDI 


Read the contents of a contact interrupt 
circular buffer, one point for each call 


RDTI 


Read the contents of a timer interrupt 
circular buffer, one entry for each call 


RDWD 


Read the contents of a contact interrupt 
circular buffer, returning 16 bits of 
module data and change-of-state 
information 


RSTI 


Read a single timer module (D) 


SCTI 


Set a timer module to an initial value 



15.5.4 AIRD/AIRDW: Performing Input of Analog Data in Random Sequence 

The ISA standard AIRD/AIRDW FORTRAN subroutines input analog data in 
random sequence. These calls are issued as follows: 



CALL 



AIRD 
AIRDW 



(inm, icont, idata , [isb] ,lun) 



inm 



The number of analog input channels. 
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icont 

An integer array containing terminal connection data-channel 
number (right-justified in bits 0-11) and gain (bits 12-15), as 
shown in Table 15-3. 



idata 

An integer array to receive the converted values. 



isb 



A 2-word integer array to which the subroutine status is 
returned . 



lun 

The logical unit number. 

NOTE 
lun is a required parameter. 

The isb array has the standard meaning defined in Section 15.5.2. If 
inm = 0, then isb(l) = 3, The contents of idata are undefined if an 
error occurs. 



15.5.5 AISQ/AISQW: Reading Sequential Analog Input Channels 

The ISA standard AISQ/AISQW FORTRAN subroutines read a series of 
sequential analog input channels. These calls are issued as follows: 



{ AIS 



[SQ i 
CALL ^ ) (inm, icont, idata , [isb] , lun) 

[SQW ) 



inm 

The number of analog input channels. 



icont 



An integer array containing terminal connection data-channel 
number (right-justified in bits 0-11) and gain (bits 12-15) , as 
shown in Table 15-3. 



idata 

An integer array to receive the converted values. 
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isb 

A 2-word integer array to which the subroutine status is 
returned , 

lun 

The logical unit number. 

NOTE 
lun is a required parameter. 

For sequential analog input, channel number is computed in steps of 
one, beginning with the value specified in the first element of icont. 
The channel number field is ignored in all other elements of the 
array. 

The gain used for each conversion is taken from the respective element 

in icont. Thus, even though the channel number is ignored in all but 

the first element of icont, the gain must be specified for each 
conversion to be performed. 

The isb array has the standard meaning defined in Section 15.5.2. If 
inm = 0, then isb{l) = 3. The contents of idata are undefined if an 
error occurs. 



15.5.6 AO/AOW: Performing Analog Output 

The ISA standard AO/AOW FORTRAN subroutines initiate analog output on 
several channels. These calls are issued as follows: 

(inm, icont, idata, [isb] , [lun] ) 



inm 

The number of analog output channels. 

icont 

An integer array containing the channel numbers. 




idata 



An integer array containing the output voltage settings, in the 
range 0-1023. 
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isb 

A 2-word integer array to which the subroutine status is 
returned . 



lun 

The logical unit number (ignored if present). 

The isb array has the standard meaning defined in Section 15.5.2. 



15.5.7 ASUDLN: Assigning a LUN to the UDCll 

The ASUDLN FORTRAN subroutine assigns the specified LUN to the 
specified unit and defines it as the default logical unit number to be 
used whenever a LUN specification is omitted from a UDCll subroutine 
call. It is issued as follows: 

CALL ASUDLN (lun , [ isw] , [ iun] ) 



lun 



isw 



lun 



The logical unit number to be assigned to the specified unit, and 
defined as the default. 



An integer variable to which the result of the ASSIGN LUN system 
directive is returned. 



An integer defining the UDCll unit number. If no number is 
specified, is assumed. 



15.5.8 CTDI : Connecting to Contact Interrupts 

The CTDI FORTRAN subroutine connects a task to contact interrupts and 
specifies a circular buffer to receive contact interrupt data. The 
length of this buffer can be computed by considering the following: 

• Rate at which contact module interrupts occur 

• Number of modules that can interrupt simultaneously 

• Rate at which the circular buffer is emptied 
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The UDCll driver generates a 5-word entry for each contact interrupt 

and the interface subroutine itself requires 10 words of additional 

storage. Thus the isz parameter, described below, can be computed as 

follows: 

isz = (10 + 5 * n) 

where n is the number of entries in the buffer and isz is expressed in 

words. 

The call is issued as follows: 

CALL CTDI (ibuf ,isz,iev, [isb] , [lun] ) 

ibuf 

An integer array that is to receive contact interrupt data. 



ISZ 



lev 



isb 



The length of the array in words, with a minimum size of 15. 



The trigger event flag number. The specified event flag is set 
whenever the driver inserts an entry in the data buffer. 



A 2-word integer array to which the subroutine status is 
returned . 



lun 

The logical unit number. 
The isb array has the standard meaning defined in Section 15.5.2. 

15.5.9 CTTI: Connecting to Timer Interrupts 

The CTTI FORTRAN subroutine connects a task to timer interrupts and 
specifies a circular buffer to receive timer interrupt data. The 
length of this buffer can be computed by considering the following: 

• Rate at which timer module interrupts occur 

• Number of modules that can interrupt simultaneously 

• Rate at which the circular buffer is emptied 
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The UDCll driver generates a 4-word entry for each timer interrupt and 
the interface subroutine itself requires 8 words of additional 
storage. Thus the isz parameter, described below, can be computed as 
follows: 

isz = (8 + 4 * n) 

where n is the number of entries in the buffer and isz is expressed in 
words. 

When a timer module interrupt occurs, the driver resets the count to 
an initial value, normally that specified in iv. The initial value 
for a specific module can be modified by calling the SCTI subroutine 
(see Section 15.5.19). 

The call is issued as follows: 

CALL CTTI (ibuf ,isz,iev,iv, [isb] , [lun] ) 

ibuf 

An integer array that is to receive timer interrupt data. 



ISZ 



lev 



IV 



isb 



The length of the array in words, with a minimum size of 12. 



A trigger event flag number. The specified event flag is set 
whenever the driver inserts an entry in the data buffer. 



An integer array that contains the initial timer module values, 
with one entry for each timer module, where entry n corresponds 
to timer module number n-1. 



A 2-word integer array to which the subroutine status is 
returned. 



lun 

The logical unit number. 
The isb array has the standard meaning defined in Section 15.5.2. 

15.5.10 DFDI: Disconnecting from Contact Interrupts 

The DFDI FORTRAN subroutine disconnects a task from contact 
interrupts. It is issued as follows: 

CALL DFDI ( [isb] , [lun] ) 
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isb 

A 2-word integer array to which the subroutine status is 
returned . 

lun 

The logical unit number. 
The isb array has the standard meaning defined in Section 15.5.2. 

15.5.11 DFTI: Disconnecting from Timer Interrupts 

The DFTI FORTRAN subroutine disconnects a task from timer interrupts. 
It is issued as follows: 

CALL DFTI ([isb] , [lun] ) 

isb 

A 2-word integer array to which the subroutine status is 
returned . 

lun 

The logical unit number. 
The isb array has the standard meaning defined in Section 15.5.2. 

15.5.12 DI/DIW: Reading Several Contact Sense Fields 

The ISA standard DI/DIW FORTRAN subroutines read several 16-point 
contact sense fields. These calls are issued as follows: 

i DI I 
CALL < > (inm,icont,idata,isb, [lun] ) 
I DIW ) 

inm 

The number of fields to be read. 



icont 



An integer array containing the initial point number of each 
field to be read. 



idata 



-..^..ige^ ^^..^Y ^.la.. j.s> uO lSCcxvc uue xnfut ddta, j.D DlCS or 

contact data for each field read. 
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isb 

A 2-word integer array to which the subroutine status is 
returned . 



lun 

The logical unit number (ignored if present) . 
The isb array has the standard meaning defined in Section 15.5.2. 

15.5.13 DOL/DOLW: Latching or Unlatching Several Fields 

The ISA standard DOL/DOLW FORTRAN subroutines latch or unlatch one or 
more 16-point fields. These calls are issued as follows: 



CALL < > (inm,icont,idata,imsk, [isb] , [lun] ) 




inm 

The number of fields to be latched or unlatched. 



icont 



An integer array containing the initial point number of each 
16-point field. 



idata 



An integer array that specifies the points to be latched or 
unlatched; bit n of idata corresponds to point number icont + n; 
if the corresponding bit in imsk is set, the bit is changed; a 
bit value of 1 indicates latching, and unlatching; each entry 
in the array specifies a string of 16 points. 



imsk 



isb 



An integer array in which bits are set to indicate points whose 
states are to be changed in the corresponding idata bits; each 
entry in the array specifies a 16-bit mask word. 



A 2-word integer array to which the subroutine status is 
returned . 



lun 

The logical unit number. 
The isb array has the standard meaning defined in Section 15.5.2. 
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15.5.14 DOM/DOMW: Pulsing Several Fields 

The ISA standard DOM/DOMW FORTRAN subroutines pulse several 16-bit 
fields (1-shot digital output points) . These calls are issued as 
follows: 




CALL < > (inm,icont,idata, [idx] , [isb] , [lun] ) 



inm 

The number of fields to be pulsed. 



icont 



An integer array containing the initial point number of each 
16-point field. 



idata 



idx 



isb 



An integer array which specifies the points to be pulsed; bit n 
of idata corresponds to point number icont + n. 



A dummy argument retained for compatibility with existing 
Instrument Society of America standard FORTRAN process control 
calls. 



A 2-word integer array to which the subroutine status is 
returned . 



lun 

The logical unit number (ignored if present). 
The isb array has the standard meaning defined in Section 15.5.2. 

15.5.15 RCIPT: Reading a Contact Interrupt Point 

The RCIPT FORTRAN subroutine reads the state of a single contact 
interrupt point. It is issued as follows: 

CALL RCIPT (ipt,isb, [lun] ) 



ipt 



The number of the point to be read; points are numbered 
sequentially from 0, the first point on the first contact 
interrupt module. 
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A 2-word integer array to which the subroutine status is 
returned . 



The logical unit number (ignored if present) 



The isb array has the same basic meaning defined in Section 15.5.2. 
However, isb word 2 is set to one of the following values, 
representing the state of the point: 

Setting Meaning 

.FALSE. (0) Point is open 

.TRUE. (-1) Point is closed 

NOTE 

To increase throughput, the subroutines 
RDCS, RDDI, RDTI, and RDWD described in 
the following four sections do not issue 
the clear Event Flag directive until a 
buffer-empty condition is detected. The 
calling task, therefore, must avoid 
issuing a Wait-For directive until a 
buffer-empty is reported. 



15.5.16 RDCS: Reading Contact Interrupt Change-of-State Data from a 
Circular Buffer 

The RDCS FORTRAN subroutine reads contact interrupt data from a 
circular buffer that was specified in a CTDI call (see Section 
15.5.8). It does no actual Input or output, but rather performs a 
point-by-point scan of an interrupt entry in the buffer, returning the 
state of each point that has changed state as a logical value. The 
trigger event flag that was specified in the CTDI call is cleared when 
the "buffer empty" condition is detected. 

On the initial call to RDCS, the module number, module data, and 
change-of-state word of the next interrupt entry are read from the 
circular buffer and stored for subsequent reference. The subroutine 
then searches the entry change-of-state word until a nonzero point is 
encountered. The point number is computed and returned to the caller 
along with the state of the point. Scanning for points that have 
changed state resumes on the next call; all other points are 
bypassed. The next entry is automatically read when the caller has 
received all change-of-state information from the current entry. If a 
valid entry is not found, ipt is set negative and ict (if specified) 
is either assigned a value of or an overrun count maintained by the 
UDCll driver. If ict is 0, no further entries remain. A nonzero 
value indicates that the driver received more data than could be 
stored in the buffer, and ict represents the number of entries that 
were discarded. 
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The RDCS call is issued as follows; 
CALL RDCS (ipt,ival, [ict] ) 



ipt 



A variable to which the digital input point number is returned; 
it may be set as follows: 



• 



ipt if no valid entry is found (that is, no interrupt data 
currently in buffer, or overrun detected). One of the 
following values is returned to indicate the condition 
detected : 

-1 = Buffer empty 

-2 = Overrun detected 

ipt => if the value indicated is a point number that has 
changed state; the state is returned to ival. 



ival 



ict 



A variable to which the state of the point is returned; it may 
be set as follows: 

• .FALSE. (0) if the point is open 

• .TRUE. (-1) if the point is closed 



An integer variable for receiving the overrun count, A nonzero 
positive count indicates that the driver was unable to store the 
number of interrupts indicated. 



15.5.17 RDDI: Reading Contact Interrupt Data from a Circular Buffer 

The RDDI FORTRAN subroutine reads contact interrupt data from a 
circular buffer that was specified in a CTDI call (see Section 
15.5.8). It does no actual input or output, but rather performs a 
polnt-by-point scan of an interrupt entry in the buffer, returning the 
state of each point as a logical value. The trigger event flag that 
was specified in the CTDI call is also cleared. 

On the initial call to RDDI, the module number and data of the next 
interrupt entry are read from the circular buffer and stored for 
subsequent reference. The subroutine then sets the current data bit 
number n to 0, examines the state of data bit n, and converts bit n to 
a point number by the following formula: 

ipt = module number * 16 + n 



15-27 



UNIVERSAL DIGITAL CONTROLLER DRIVER 

On each subsequent call, n is incremented by one and then data _ bit n 
is examined in the stored module data. When n reaches 16, it is reset 
to and an attempt is made to read the next interrupt entry from the 
circular buffer. If a valid entry is not found, ipt is set negative 
and ict (if specified) is either assigned a value of or an overrun 
count maintained by the UDCll driver. If ict is 0, no further entries 
remain. A nonzero value indicates that the driver received more data 
than could be stored in the buffer, and ict represents the number of 
entries that were discarded. 

The RDDI call is issued as follows: 

CALL RDDI (ipt,ival,[ict] ) 



ipt 



A variable to which the digital input point number is returned; 
it may be set as follows: 

• ipt if no valid entry is found (that is, no interrupt data 
currently in buffer, or buffer empty). One of the following 
values is returned to indicate the condition detected: 

-l=Buffer empty 
-2=0verrun detected 

• ipt => if the value indicated is a point number; the state 
is returned to ival 



ival 



ict 



A variable to which the state of the point is returned; it may 
be set as follows: 

• .FALSE. (0) if the point is open 

• .TRUE. (-1) if the point is closed 



A variable to which the overrun count may be returned; a nonzero 
positive count indicates that the driver was unable to store the 
number of entries indicated. 



15.5.18 RDTI: Reading Timer Interrupt Data from a Circular Buffer 

The RDTI FORTRAN subroutine reads timer interrupt data from a circular 
buffer that was specified in a CTTI call (see Section 15.5.9). It 
does no actual input or output, but rather performs a scan of each 
entry in the buffer, returning the timer value for each call. The 
trigger event flag that was specified in the CTTI call is also 
cleared. 

When a timer module interrupt occurs, the UDCll driver resets the 
count to an initial value, usually that specified in the iv array on 
the CTTI call. The initial value can be modified for a specific 
module by calling the subroutine SCTI (see Section 15.5.19). 
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The RDTI call is issued as follows; 
CALL RDTI (imod,itm, [ivrn] ) 



imod 



itm 



A variable to which the module number is returned; it may be set 
as follows: 

• imod if no valid entry is found (that is, no interrupt data 
currently in buffer, or buffer empty) . One of the following 
values is returned to indicate the condition detected: 

-l=Buffer empty 
-2=0verrun detected 

• imod > if the entry is valid, indicating a module number; 
the value of the timer module is returned in itm 



A variable to which the timer value is returned, 



ivrn 



A variable to which the overrun count may be returned; a nonzero 
positive count indicates that the driver was unable to store the 
number of values indicated. 



15.5.19 RDWD: Reading a Full Word of Contact Interrupt Data from the 
Circular Buffer 

The RDWD FORTRAN subroutine reads a full word of contact interrupt and 
change-of-state data from the circular buffer that was specified in a 
CTDI call (see Section 15.5.8). It does no actual input or output, 
but rather performs a scan of each entry, returning the state of a 
module and, optionally, the change-of-state data for each call. The 
trigger event flag specified in the call to CTDI is cleared. 

The call to RDWD is issued as follows: 

CALL RDWD ( imod , ist ,[ ivrn] ,[ icos] ) 



imod 



A variable to which the module number is returned; it may be set 
as follows: 

• imod if no valid entry is found (that is, no interrupt data 
currently in buffer .or overrun detected). One of the 
following values is returned to indicate the condition 
detected : 

-l=Buffer empty 
-2=0verrun detected 
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ist 

A variable to which the module data is returned. 

ivrn 

A variable to which the overrun count may be returned; a 
nonzero, positive count indicates that the driver was unable to 
store the number of entries indicated. 



icos 



A variable to which the change-of-state data is returned. One 
bit is set for each point that has changed state in the direction 
indicated by the "point open" (POP) or "point closed" (PCL) 
jumpers on the module. 



15.5.20 RSTI: Reading a Timer Module 

The RSTI FORTRAN subroutine reads a single timer module. It is issued 
as follows: 

CALL RSTI (imod,isb, [lun] ) 

imod 

The module number of the timer to be read. 



isb 



A 2-word integer array to which the subroutine status is 
returned . 



lun 



The logical unit number (ignored if present). 
The isb array has the standard meaning defined in Section 15.5.2. 

15.5.21 SCTI: Initializing a Timer Module 

The SCTI FORTRAN subroutine sets a timer module to an initial value. 
It is issued as follows: 

CALL SCTI (imod, ival , [isb] , [lun] ) 

imod 

The module number of the timer to be set. 
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ival 



The initial timer value. 



isb 



A 2-word integer array to which the subroutine status is 
returned. 



lun 

The logical unit number. 

The isb array has the standard meaning defined in Section 15.5.2. 

Calls to initialize a counter are valid only if the issuing task has 
connected a buffer for receiving counter interrupts by a call to CTTI. 

15.6 STATUS RETURNS 

Table 15-6 lists the error and status conditions that are returned by 
the UDCll driver described in this chapter: 



Table 15-6 
UDCll Status Returns 



Code 


Reason 


IS. sue 


Sucessful completion 




The operation specified in the QIO directive was 
completed successfully. The second word of the I/O 
status block can be examined to determine the number 
of samples completed or converted. 


IS.PND 


I/O request pending 




The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 


IE. ABO 


Operation aborted 




The specified I/O operation was canceled with lO.KIL 
while still in the I/O queue. 


IE. BAD 


Bad parameter 




An illegal specification was supplied for one or more 
of the device-dependent QIO parameters (words 6-11) . 
For the UDCll, this code indicates an illegal channel 
number or gain code for the ADUOl. 



(continued on next page) 
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Table 15-6 (Cont.) 
UDCll Status Returns 



Code 



Reason 



IE. BYT Byte-aligned buffer specified 

Byte alignment was specified for a buffer but only 
word alignment is legal for the UDC12. Alternately, 
the length of a buffer was not an even number of 
bytes. 

IE. CON Connect error 



lE.DNR 



lE.IEF 



The task attempted to connect to contact or timer 
interrupts, but the interrupt was already connected 
to another task. Only one task can be connected to a 
timer or contact interrupt. Alternately a task which 
was not connected attempted to disconnect from 
contact or timer interrupts. 

Device not ready 

The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. For the ADUOl, this code is returned if 
an interrupt time out occurred or the power failed. 

Invalid event flag number 

An invalid trigger event flag number was specified in 
a connect function. 



IE. IPC Illegal function 

A function code was included in an I/O request that 
is illegal for the UDCll, or a request to initialize 
a counter (lO.ITI) was issued by a task that was not 
connected to receive counter interrupts. The 
function may also refer to a UDCll feature which was 
not specified at system generation. 

IE. MOD Invalid UDCll module 



lE.OFL 



On latching output, the user specified a starting 
point number that was not legal (defined at system 
generation) or was not evenly divisible by 16. 

Device off line 



The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. 

(continued on next page) 
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Table 15-6 (Cont.) 
UDCll Status Returns 



Code 



Reason 



lE.PRI 



lE.SPC 



Privilege violation 

The task which issued the request was not privileged 
to execute that request. For the UDCll, this code 
indicates that a checkpointable task attempted to 
connect to timer or contact interrupts. 

Illegal address space 

The specified control, data, or interrupt buffer was 
partially or totally outside the address space of the 
issuing task. Alternately, the interrupt buffer was 
too small for a single data entry (six words for 
timer interrupts and seven words for contact 
interrupts), or a byte count of was specified. 



FORTRAN interface values for these status returns are presented 
Section 15.6.1. 



in 



15.6.1 FORTRAN Interface Values 

The values listed in Table 15-7 are returned in FORTRAN subroutine 
calls. 



Table 15-7 
FORTRAN Interface Values 



Status Return 


FORTRAN Value 


IS. sue 


+01 


IS.PND 


+00 


IE. ABO 


+315 


lE.ADP 


+101 


IE. BAD 


+301 


IE. BYT 


+319 


lE.DAO 


+313 


lE.DNR 


+303 


lE.IEF 


+100 


lE.IFC 


+302 


lE.ILU 


+99 


IE. MOD 


+ 321 


lE.ONP 


+ 305 


lE.PRI 


+ 316 


lE.RSU 


+ 317 


lE.SDP 


+ 102 


lE.SPC 


+ 306 


lE.ULN 


+08 


lE.UPN 


+04 
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15.7 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the UDCll driver described in this 
chapter. 



15.7.1 Numbering Conventions 

Numbering is relative. Module numbers start at 0, beginning with the 
first module of a given type. 

Channel numbers also start at 0, with channel as the first channel 
on the first module of a given type. For the ADUOl, channel 8 is the 
first channel on the second analog output module. 

Each lAD-IA module installed in an ICSll subsystem occupies 120 

channels (regardless of the number of multiplexers installed) . In 

this case, channel 120 is the first channel on the second lAD-IA A/D 
converter. 

Point numbers start at 0, with point as the first point on the first 
module of a given type. For instance, point 20(8) is the first point 
of the second contact sense module (that is, relative module number 
1). 



15.7.2 Processing Circular Buffer Entries 

Circular buffer entries should be processed in the following sequence. 

1. Execute a WAITFOR system directive using the trigger event 
flag specified in the subroutine called to connect the 
circular buffer (CTTI or CTDI) . 

2. Repeatedly call the appropriate subroutine to read the 
circular buffer until all entries have been obtained and ipt 
indicates that the buffer is empty (-1). 

3. Perform any other processing and return to step 1. 
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LABORATORY PERIPHERAL SYSTEMS DRIVERS 



16.1 INTRODUCTION 

The LPSll and ARll Laboratory Peripheral Systems are modular, 
real-time subsystems used for the acquisition and/or output of 
laboratory analog data. (Laboratory Peripheral Systems drivers are 
not supported on RSX-llM-PLUS systems.) Table 16-1 compares the LPSll 
with the ARll. 



Table 16-1 
Laboratory Peripheral Systems 





LPSll 


ARll 


Analog-to-Digital Conversion 
(with Sample and Hold 
Circuitry) 


12 bits of precision 
16-channel multiplexer 
with gain ranging 

Maximum of 64 channels 
without gain ranging 


10 bits of precision 
16-channel multiplexer 
without gain ranging 


Programmable Real-Time Clock 


Yes 


Yes 


Digital-to-Analog Output 


12 bits of precision 
10 channels (includ- 
ing display) 


10 bits of precision 
2 channels (including 
display) 


Display Control 


4096 by 4096 dot matrix 


1024 by 1024 dot matrix 


Digital I/O Option 


16 digital points 
and programmable 
relays 


16 digital points 
(available with 
DRll-K option) 



At system generation, the user can specify the following: 

• The number of A/D channels 

• The presence or absence of the gain-ranging option (LPSAM-SG) 
(LPSll only) and the polarity of each channel (uni- or 
bipolar) 

• The presence or absence of the external D/A option (LPSVC and 
LPSDA) , and if present, the number of D/A channels 

• The clock preset value 
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16.1.1 ARll Laboratory Peripheral System 

The ARll is a 1-module, real-time analog subsystem that interfaces to 
the PDP-11 family of computers by a "hex" small peripheral controller 
slot. The system is a subset of the LPSll and, as such, enjoys the 
same degree of flexibility. The ARll includes a 16-channel, 10-bit 
A/D converter with sample-and-hold , a programmable real-time clock 
with one external input, and a display control with two 10-bit D/A 
converters. 



16.1.2 LPSll Laboratory Peripheral System 



The LPSll is a high 
flexibility of serv 
research, analytica 
monitoring, data 
technical education 
designed for easy 
13-bit A/D converte 
triggers, a displ 
16-bit digital I/O 
added to the basic 



-performance, modular, real- 
ing a variety of application 
1 instrumentation, data coll 
logging, industrial test 
The basic subsystem, buil 
interface with external inst 
r, a programmable real-time 
ay controller with two 12-bi 
option. Up to nine differen 
package. 



time subsystem with the 
s, including biomedical 
ection and reduction, 
ing, engineering, and 
t in a compact size and 
rumentation, includes a 
clock, with two Schmitt 
t D/A converters, and a 
t option types may be 



16.2 GET LUN INFORMATION MACRO 

If a GET LUN INFORMATION system directive is issued for a LUN 
associated with a Laboratory Peripheral System, word 2 (the first 
characteristics word) contains all Os words 3 and 4 are undefined, and 
word 5 contains a 16-bit buffer preset value that controls the rate of 
the real-time clock interrupts, as explained in Section 16.6.1. 



16.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
the Laboratory Peripheral System drivers. 



16.3.1 Standard QIO Function 

Table 16-2 lists the standard function of the QIO macro that is valid 
for the Laboratory Peripheral Systems. 



Table 16-2 
Standard QIO Function for 
Laboratory Peripheral Systems 



Format 


Function 


QIO$C lO.KIL,... 


Cancel I/O requests 



lO.KIL cancels all queued and in-progress I/O requests. 
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16.3.2 Device-Specific QIO Functions (Immediate) 

Except for lO.STP (see Section 16.3.4), all device-specific functions 
of the QIO macro that are valid for the Laboratory Peripheral Systems 
are either immediate or synchronous. Each immediate function performs 
a complete operation, whereas each synchronous function simply 
initiates an operation synchronized to the real-time clock. Table 
16-3 lists the immediate functions. 



Table 16-3 
Device-Specific QIO Functions for the 
Laboratory Peripheral Systems (Immediate) 



Format 


Function 


QIO$C lO.LED, . . . ,<int,num> 

QIO$C lO.REL,. .. ,<rel,pol> 
QIO$C lO.SDI,. . . ,<mask> 
QIOSC lO.SDO, .. . ,<mask,data> 


DISPLAY number in LED lights 
(LPSll only) 

LATCH output relay (LPSll only) 

READ digital input register 

WRITE digital output register 



int 



num 



rel 



pol 



mask 



The 16-bit signed binary integer to display. 



The LED digit number where the decimal point is to be placed, 



The relay number (0 or i; 



The polarity (0 for open, nonzero for closed) 



data 



The mask word. 



The data word, 



The following subsections describe the functions listed above, 
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lfi.3.2.1 10. LED - This LPSll-only function displays a 16-bit signed 
binary integer in the light-emitting diode (LED) lights. The number 
is displayed with a leading blank (positive number) or minus sign 
(negative number) , followed by five non-zero-suppressed decimal digits 
that represent the magnitude of the number, LED digits are numbered 
from right to left, starting at 1, 

The number may be displayed with or without a decimal point. If the 
parameter num is a number from 1 to 5, then the corresponding LED 
digit is displayed with a decimal point to the right of the digit. If 
the LED digit number is not a number from 1 to 5, then no decimal 
point is displayed. 



16.3.2.2 lO.REL - This LPSll-only function opens or closes the 
programmable relays in the digital I/O status register. Approximately 
300 milliseconds are required to open or close a relay. The driver 
imposes no delays when executing this function. Thus it is the 
responsibility of the user to insure that adequate time has elapsed 
between the opening and closing of a relay. 



16.3.2.3 lO.SDI - This function reads data qualified by a mask word 
from the digital input register. The mask word contains a 1 in each 
bit position from which data is to be read. All other bits are zero 
filled and the resulting value is returned in the second I/O status 
word . 

The operation performed is: 

RETURN VALUE=MASK. AND. INPUT REGISTER 



16.3.2.4 lO.SDO - This function writes data qualified by a mask word 
into the digital output register. The mask word contains a 1 in each 
bit position that is to be written. The data word specifies the data 
to be written in corresponding bit positions. 

The operation performed is: 

NEW REGISTER=<MASK.AND.DATA>.OR.<<.NOT.MASK>.AND.OLD REGISTER> 



16.3.3 Device-Specific QIO Functions (Synchronous) 

Table 16-4 lists the synchronous, device-specific functions of the QIO 
macro that are valid for the Laboratory Peripheral Systems. 
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Table 16-4 
Device-Specific QIC Functions for the 
Laboratory Peripheral Systems (Synchronous) 



Format 



QIO$C 10. ADS,. 
QIO$C 10. HIS,. 
QIO$C lO.MDA,. 
QIO$C lO.MDI,. 
QIO$C lO.MDO,. 



. ,<stadd,size,pnt, 
ticks, bufs,chna> 

. ,<stadd,size,pnt, 
ticks, bufs> 

. ,<stadd ,size,pnt, 
ticks, bufs,chnd> 

. ,<stadd,size,pnt, 
ticks,buf s,mask> 

. ,<stadd ,size,pnt, 
ticks,bufs,mask> 



Function 



INITIATE A/D sampling 



INITIATE histogram sampling 
(LPSll only) 

J.N X J. X ri J. 1-j i-'/ n Oui-pUL. 



INITIATE digital input 
sampling 

INITIATE digital output 



stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



size 



pnt 



The data buffer size in bytes (must be greater than and a 
multiple of four bytes) . 



The digital point numbers (byte - starting input/output point 

number; byte 1 - input point number to stop the function). 

Points are numbered from to 15, allowing a maximum of 16 points 
to be specified. 



ticks 



The number of real-time clock ticks between samples or data 
transfers, as appropriate. 



bufs 



The number of data buffers to transfer, 
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The analog-to-digital conversion specification. Byte contains 
the starting channel number. For LPSll this must be in the range 
of 0-63; for ARll the range is 0-15. If the LPSll gain-ranging 
option is present, the channel number must be in the range of 
0-15, and bits 4 and 5 specify the gain code. 

Byte 1 contains the number of consecutive analog-to-digital 
channels to sample. For LPSll this must be in the range of 1-64; 
for ARll or the LPSll with gain-ranging, the range is 1-16. 



chnd 



The digital-to-analog output channel specification. Byte 
contains the starting channel number. For LPSll this must be in 
the range of 0-9; for the ARll the range is 0-1. 

Byte 1 contains the number of consecutive channels to be output. 
For LPSll this must be in the range of 1-10; for ARll the range 
is 1-2. 



mask 

The mask word. 
The following subsections describe the functions listed above. 



16.3.3.1 10. ADS - This function reads one or more A/D channels at 
precisely timed intervals, with or without auto gain-ranging. If two 
or more channels are specified, all are sampled at approximately the 
same time, once per interval- 
Sampling may be started when the request is dequeued or when a 
specified digital input point is set. A digital output point may 
optionally be set when sampling is started. Sampling may be 
terminated by a program request (lO.STP or lO.KIL), by the clearing of 
a digital input point, or by the collection of a specified number of 
buffers of data. 

All input is double buffered with respect to the user task. Each time 
a half buffer of data has been collected, the user task is notified 
(by the setting of an event flag) that data is available to be 
processed while the driver fills the other half of the buffer. If the 
user task does not respond quickly enough, a data overrun may result. 
This occurs if the driver attempts to put another data item in the 
user buffer when no space is available. 

The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. In addition, setting bit 3 to a 1 means LPSll auto 
gain-ranging is requested. Bit 3 is ignored for the ARll. If bits 7 
and 6 are both set to 1, the digital input point and digital output 
point number are assumed to be the same. 
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If LPSll auto gain-ranging is used, the LPSAM-SG hardware option must 
be present and specified at system generation. The auto gain-ranging 
algorithm causes a channel to be sampled at the highest gain at which 
saturation does not occur. If the gain-ranging option is present and 
auto gain-ranging is not specified in bit 3 of the subfunction code, 
then bits 4 and 5 of the starting channel number specify the gain at 
which samples are to be converted. Gain codes are as follows: 

Code Gain 

00 1 

01 4 

10 16 

11 64 

Data words written into the user buffer contain the converted value in 
bits 0-11 and the gain code, as shown below, in bits 12-15: 

Code Gain 

0000 1 

0001 4 

0010 16 

0011 64 

If the LPSAM-SG option is present, then each channel must have been 
defined as uni- or bipolar at system generation. In addition, if 
bandwidth filtering is enabled (and so indicated at system generation 
time) , a software delay is imposed by the driver when the multiplexer 
channel is changed. This delay must have been specified at SYSGEN. 
See the LPSll Laboratory Peripheral System User' s Guide . 

The ARll always returns data that is equivalent to an LPSll gain of 1. 
Channel polarity must always be specified for the ARll at system 
generation, since this operation is software selectable at the time 
sampling is initiated. 



16.3.3.2 10. HIS - This LPSll-only function measures the elapsed time 
between a series of events by means of Schmitt trigger 1. Each time a 
sample is to be taken, a counter is incremented and Schmitt trigger 1 
is tested. If it has fired, then the counter is written into the user 
buffer and reset to 0. Thus, the data item returned to the user is 
the number of sample intervals between Schmitt trigger firings. 

If the counter overflows before Schmitt trigger 1 fires, then a 
value is written into the user buffer. Sampling may be started and 
stopped as described in Section 16.3.3.1. All input is double 
buffered with respect to the user task. 

The subfunction modifier bits appear below. A setting of 1 indicates 
the action listed in the right-hand column. 
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Bit Meaning 

0-3 Unused 

4 Stop on number of buffers 

5 Stop on digital input point clear 

6 Set digital output point at start of operation 

7 Start on digital input point set (a 
specification means start immediately) . Points 
are numbered from to 15, allowing a maximum of 
16 points to be specified. 



16.3.3.3 lO.MDA - This function writes data into one or more external 
D/A converters at precisely timed intervals. If two or more channels 
are specified, all are written at approximately the same time, once 
per interval. Output may be started or stopped as described in 
Section 16.3.3.1. All output is double buffered with respect to the 
user task. 

D/A converters and 1 correspond to the X and Y registers of the 
display control. Note that there are no specific driver functions to 
set the display status register. This is reserved for the user. D/A 
converters 2 through 9 correspond to the LPSll, LPSDA external D/A 
option. 

The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. 



16.3.3.4 lO.MDI - This function provides the capability to read data 
qualified by a mask word from the digital input register at precisely 
timed intervals. Sampling may be started and stopped as described in 
Section 16.3.3.1. All input is double buffered with respect to the 
user task. 

The mask word contains a 1 in each bit position from which data is to 
be read. All other bits are 0. 

The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. 



16.3.3.5 lO.MDO - This function writes data qualified by a mask word 
into the digital output register at precisely timed intervals. Output 
may be started and stopped as described in Section 16.3.3.1. All 
output is double buffered with respect to the user task. 

The subfunction modifier bits are identical to those described in 
Section 16.3.3.2. 
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16.3.4 Device-Specific QIO Function (lO.STP) 

Table 16-5 lists the device-specific function of the QIO macro, which 
is valid for the Laboratory Peripheral Systems. 



Table 16-5 

Device-Specific QIO Function for the 

Laboratory Peripheral Systems (lO.STP) 



Format 


Function 


QIO$C lO.STP,... 


,<STADD> 


STOP In-progress request 



stadd 



The buffer address of the function to stop (must be the same as 
the address specified in the initiating request) . 



16.3.4.1 lO.STP - lO.STP stops a single, in-progress synchronous 
request. It is unlike lO.KIL in that it cancels only the specified 
request, whereas lO.KIL cancels all requests. 



16.4 FORTRAN INTERFACE 

A collection of FORTRAN-callable subroutines provide FORTRAN programs 
access to the Laboratory Peripheral Systems. These routines are 
described in this section. 

Some of these routines may be called from FORTRAN as either 
subroutines or functions. All are reentrant and may be placed in a 
resident library. 



16.4.1 The isb Status Array 

The isb (I/O status block) parameter is a 2-word integer array that 
contains the status of the FORTRAN call, in accordance with ISA 
convention. This array serves two purposes: 

1. It is the 2-word I/O status block to which the driver returns 
an I/O status code on completion of an I/O operation. 

2. The first word of the isb receives a status code from the 
FORTRAN interface in ISA-compatible format, with the 
exception of the I/O pending condition, which is indicated by 
a status of 0. The ISA standard code for this condition is 
+2. 



The meaning of its contents varies, depending on the FORTRAN call that 
has been executed, but Table 16-6 lists certain general principles 
that apply. T'h 
more details. 



hat apply. The sections describing individual subroutines provide 
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Table 16-6 
Contents of First Word of isb 



Contents 


Meaning 


isb(l) = 
isb(l) = 1 
Isb(l) = 3 

3 < = isb(l) < 300 

isb(l) > 300 


Operation pending; I/O in progress 

Successful completion 

Interface subroutine unable to generate QIO 
directive, or illegal time or buffer value 

QIO directive rejected and actual error 
code = -(isb(l) - 3) 

Driver rejected request and actual error 
code = -(isb(l) - 300) 



FORTRAN interface routines depend on asynchronous system traps to set 
their status. Thus, if the trap mechanism is disabled, proper status 
cannot be set. 



16.4.2 Synchronous Subroutines 

RTS, DRS, HIST (LPSll only), SDO, and SDAC are FORTRAN subroutines 
that initiate synchronous functions. When they are used, the 
appropriate Laboratory Peripheral System driver and the FORTRAN 
program communicate by means of a caller-specified data buffer of the 
following format: 



BUFFER HEADER 



START OF DATA 
HALF BUFFER 
END OF BUFFER 



CURRENT BUFFER POINTER 



ADDRESS OF SECOND I/O STATUS WORD 



ADDRESS OF END OF BUFFER + 1 



ADDRESS OF START OF DATA 



The buffer header is initialized when the synchronous function 
initiation routine is called. The length of the buffer must be even 
and greater than or equal to 6. An even length is required so that 
the buffer is exactly divisible into half buffers. 

The drivers perform double buffering within the half buffers. Each 
time a driver fills or empties a half buffer, it sets a user-specified 
event flag to notify the user task that more data is available or 
needed. The user task responds by putting more data into the buffer 
or by removing the data now available. 

If the user task does not respond quickly enough, a data overrun may 
result. This occurs if the driver attempts to put another data item 
in the user buffer when no space is available (that is, the buffer is 
full of data) , or if the driver attempts to obtain the next data item 
from the user buffer when none is available (that is, the buffer is 
empty) . 
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All synchronous functions can be initiated immediately or when a 
specified digital input point is set (that is, a start button is 
pushed) . 

They can be terminated by any combination of a program request, the 
processing of the required number of full buffers of data, or the 
clearing of a specified digital input point (that is, a stop button is 
pushed) . A digital output point may also optionally be set at the 
start of a synchronous function. This could be used, for example, as 
a signal to start a test instrument. 



16.4.3 FORTRAN Subroutine Summary 

Table 16-7 lists the FORTRAN interface subroutines supported for the 
Laboratory Peripheral Systems under RSX-llM. S and F indicate whether 
they can be called as subroutines or functions, respectively. 

Table 16-7 
FORTRAN Interface Subroutines for Laboratory Peripheral Systems 



Subroutine 


Function 


ADC 


Read a single A/D channel (F,S) 




ADJLPS 


Adjust buffer pointers (S) 




ASARLN 


Assign a LUN to ARO: (S) 




ASLSLN 


Assign a LUN to LSO: (S) 




CVSWG 


Convert a switch gain A/D value to floating point 


(F) 


DRS 


Initiate synchronous digital input sampling (S) 




HIST 


Initiate histogram sampling (S) (LPSll only) 




IDIR 


Read digital input (F,S) 




IDOR 


Write digital output (F,S) 




IRDB 


Read data from a synchronous function input buffer 
(F,S) 


LED 


Display number in LED lights (S) (LPSll only) 




LPSTP 


Stop an in-progress synchronous function (S) 




PUTD 


Put data into a synchronous function output buffer 


(S) 


RELAY 


Latch an output relay (S) (LPSll only) 




RTS 


Initiate synchronous A/D sampling (S) 




SDAC 


Initiate synchronous D/A output (S) 




SDO 


Initiate synchronous digital output (S) 





The following subsections briefly describe the function and format of 
each FORTRAN subroutine call. 
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16.4.4 ADC: Reading a Single A/D Channel 

The ADC FORTRAN subroutine or function reads a single converted value 
from an A/D channel. If the gain-ranging option is present in the 
LPSll hardware, the channel may be converted at a specific gain or the 
driver can select the best gain (the gain providing the most 
significance) . The converted value is returned as a normalized 
floating-point number. The call is issued as follows: 

CALL ADC (ichan, [var] , [igain] , [isb] ) 

ichan 

The A/D channel to be converted. 



var 



A floating-point variable that receives the converted value in 
floating-point format. 



igam 



The gain at which the specified A/D channel is to be converted. 
The default is 1. If specified, igain may have the following 
values: 

igain Gain 

Auto gain-ranging (driver selects gain that 
provides most significance) 

1 1 

2 4 

3 16 

4 64 

A gain of 1 is always used by the ARll driver. 

isb 

A 2-word integer array to which the subroutine status is 
returned . 

The isb array has the standard meaning described in Section 16.4.1. 

When the function form of the call is used, the value of the function 
is the same as that returned in var. If this value is negative, an 
error has occurred during the A/D conversion (see Section 16.5.3). 
Otherwise, this value is a floating-point number calculated from the 
following formula: 

var = (64 * converted value) / conversion gain 
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16.4.5 ADJLPS: Adjusting Buffer Pointers 

The ADJLPS FORTRAN subroutine adjusts buffer pointers for a buffer 
that a laboratory peripheral system driver is either synchronously 
filling or emptying. It is usually called when indexing is being used 
for direct access to the data in a buffer. 

When data in a buffer is to be processed only once, the IRDB and PUTD 
routines may be used. In some cases, however, it is useful to leave 
data in the buffer until processing is complete. The user program can 
process the data directly, and then call ADJLPS to free half the 
buffer. Using the routine for synchronous output functions is quite 
similar. When a half buffer of data is ready for output, ADJLPS is 
called to make the half buffer available. 

When ADJLPS is used for either input or output, care must be taken to 
insure that the program stays in sync with the driver. If the program 
loses its position with respect to the driver, the function must be 
stopped and restarted. An attempt to over-adjust will cause a 3 to be 
returned in isb(l) and no adjustment to take place. 

The call is issued as follows: 

CALL ADJLPS { ibuf , iad j , [ isb] ) 



ibuf 



iadj 



isb 



An integer array that was previously specified in a synchronous 
input or output function. 



The adjustment to be applied to the buffer pointers. For an 
input function, this specifies the number of data values that 
have been removed from the data buffer. For an output function, 
this specifies the number of data values that have been put into 
the data buffer. 



A 2-word integer array to which the subroutine status is 
returned . 



The isb array has the standard meaning described in Section 16.4.1. 



16.4.6 ASLSLN: Assigning a LUN to LSO: 

The ASLSLN FORTRAN subroutine assigns a logical unit number (LUN) to 
the LPSll. It must be called prior to executing any other Laboratory 
Peripheral Systems FORTRAN function or subroutine. Subsequent calls 
to other interface routines then implicitly reference the LPSll with 
the LUN assigned. 
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The call is issued as follows: 

CALL ASLSLN (lun , [ isb] , [ iun] ) 

lun 

The number of the LUN to be assigned to LSO: 

isb 

A 2-word integer array to which the subroutine status is 
returned. 



lun 

The unit number of the device to be assigned (defaults to if 
not specified) . 

The isb array has the standard meaning described in Section 15.4.1. 



16.4.7 A'SARLN: Assigning a LUN to ARO: 

The ASARLN FORTRAN subroutine assigns a logical unit number (LUN) to 
the ARll. It must be called prior to executing any other laboratory 
peripheral system FORTRAN function or subroutine. Subsequent calls to 
other interface routines then implicitly reference the ARll with the 
LUN assigned. 

The call is issued as follows: 

CALL ASARLN (lun , [ isb] , [ iun] ) 

lun 

The number of the LUN to be assigned to ARO:. 



isb 



A 2-word integer array to which the subroutine status is 
returned . 



lun 



The unit number of the device to be assigned (defaults to if 
not specified) . 

The isb array has the standard meaning described in Section 16.4.1. 
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16.4.8 CVSWG: Converting a Switch Gain A/D Value to Floating-Point 

The CVSWG FORTRAN subroutine converts an A/D value from a synchronous 
A/D sampling function to a floating-point number. Each data item 
returned by a laboratory peripheral system driver consists of a gain 
code and converted value packed in a single word (see Section 
16.3.3.1). This form is not readily usable by FORTRAN, but is much 
more efficient than converting each value to floating point in the 
driver. This routine unpacks the gain code and value, and then 
converts the result to a floating-point number. It can be 
conveniently used in conjunction with the IRDB routine (see Section 
16.4.13) . 

The call is issued as follows: 

CVSWG (ival) 

ival 

The value to be converted to floating point. Its format must be 
that returned by a synchronous A/D sampling function. The 
conversion is performed according to the following formula: 

var = (64 * converted value) /conversion gain 

For the various gain codes, 

var = X * converted value 

as shown below: 

Gain x 

1 64 

4 15 

16 4 

64 1 

16.4.9 DRS: Initiating Synchronous Digital Input Sampling 

The DRS FORTRAN subroutine reads data qualified by a mask word from 
the digital input register at precisely timed intervals. Sampling may 
be started or stopped as for RTS (see Section 16.4.18) and all input 
is double buffered with respect to the user task. Data may be 
sequentially retrieved from the data buffer by the IRDB routine (see 
Section 16.4.12), or the ADJLPS routine (see Section 16.4.5) may be 
used in conjunction with direct access to the input data. The call is 
issued as follows: 

CALL DRS (ibuf,ilen,imode, irate, iefn,imask,isb, [nbuf] , 
[istart] , [istop] ) 



16-15 



LABORATORY PERIPHERAL SYSTEMS DRIVERS 

ibuf 

An integer array that is to receive the input data values. 

lien 

The length of ibuf (must be even and greater than or equal to 6) . 

imode 

The start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values shown 
below. 

Function 
Selection 
Value Meaning 

128 Start on digital input point set 

64 Set digital output point at start 

32 Stop on digital input point clear 

16 Stop on number of buffers 

Thus, a value of 192 for imode specifies: 

• The sampling is to be started when a specified digital input 
point is set. 

• A digital output point is to be set when sampling is started. 

• Sampling will be stopped by a program request. 



irate 



iefn 



A 2-word integer array that specifies the time interval between 
digital input samples. The first word specifies the interval 
units as follows: 

irate(l) Unit 

1 Real-time clock ticks 

2 Milliseconds 

3 Seconds 

4 Minutes 

The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 



The number of the event flag that is to be set each time a half 
buffer of data has been collected. 
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imask 

The digital input points to be read. 

isb 

A 2-word integer array to which the subroutine status is 
returned . 



nbuf 



The number of buffers of data to be collected. It is needed only 
if a function selection value of 16 has been added into imode. 



istart 



The digital input pointer number to be used to trigger sampling, 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. 

istop 

The digital input point number to be used to stop sampling. It 
is needed only if a function selection value of 32 has been added 
into imode. 

When sampling is in progress, the first word of the isb array is zero 
and the second word contains the number of data values currently in 

the buffer. 



16.4.10 HIST: Initiating Histogram Sampling (LPSll only) 

The HIST FORTRAN subroutine measures the elapsed time between a series 
of events with Schmitt trigger 1. 

Each time a sample is to be taken, a counter is incremented and 
Schmitt trigger 1 is tested. If it has fired, then the counter is 
written into the user buffer and the counter is reset to 0. Thus the 
data returned to the user is the number of sample intervals between 
Schmitt trigger firings. If the counter overflows before Schmitt 
trigger 1 fires, a value is written into the user buffer. Sampling 
may be started and stopped as for RTS (see Section 16.4.18) and all 
input is double buffered with respect to the user task. The call is 
issued as follows: 

CALL HIST (ibuf ,ilen, imode, irate, iefn, isb, [nbuf ] , 
[istart] , [istop] ) 

ibuf 

An integer array that is to receive the input data values. 
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ilen 

The length of ibuf (must be even and greater than or equal to 6) , 

imode 

The start, stop, and sampling mode. Its value is encoded by 
adding the appropriate function selection values shown below: 

Function 
Selection 
Value Meaning 

128 Start of digital input point set 

64 Set digital output point at start 

32 Stop on digital input point clear 

16 Stop on number of buffers 



irate 



A 2-word integer array that specifies the time interval between 
samples. The first word specifies the interval units as follows: 

irate(l) Unit 

1 Real-time clock ticks 

2 Milliseconds 

3 Seconds 

4 Minutes 



The second word specifies the interval magnitude as a 16-bit 
signed integer. 



iefn 



The number of the event flag that is to be set each time a half 
buffer of data has been collected. 



isb 



A 2-word integer array to which the subroutine status is 
returned . 



nbuf 



The number of buffers of data to be collected. It is needed only 
if a function selection value of 16 has been added into imode. 
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istart 



The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. 



istop 



The digital input point number to be used to stop sampling. It 
is needed only if a function selection value of 32 has been added 
into imode. 



The Isb array has the standard meaning described in Section 16.4.1. 

When sampling is in progress, the first word of the isb array is and 
the second word contains the num.ber of data values currently in the 
buffer. 



16.4.11 IDIR: Reading Digital Input 

The IDIR FORTRAN subroutine or function reads the digital input 
register as an unsigned binary integer, or as four binary-coded 
decimal (BCD) digits. In the latter case, the BCD digits are 
converted to a binary integer before the value is returned to the 
caller. The call is issued as follows: 

CALL IDIR (imode, [ival] , [isb] ) 

imode 

The mode in which the digital input register is to be read. If 
imode equals 0, then the digital input register is read as four 
BCD digits and converted to a binary integer. Otherwise, it is 
read as a 16-bit unsigned binary integer. 

ival 

A variable that receives the value read. 

isb 

A 2-word integer array to which the subroutine status is 
returned. 

The isb array has the standard meaning described in Section 16.4.1. 

When the function form of the call is used, the value of the function 
is the same as that returned in ival. 
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16.4.12 IDOR: Writing Digital Output 

The IDOR FORTRAN subroutine or function clears or sets bits in the 
digital output register. The caller provides a mask word and output 
mode. Bits in the digital output registers corresponding to the bits 
specified in the mask word are either set or cleared according to the 
specified mode. The call is issued as follows: 

CALL IDOR (imode,lmask, [newval] , [isb] ) 

imode 

Whether the bits specified by imask are to be cleared or set in 
the digital output register. If imode equals 0, then the bits 
are to be cleared. Otherwise, they are to be set. 



imask 



The bits to be cleared or set in the digital output register. It 
may be conveniently specified as an octal constant. 



newval 



A variable that receives the updated (actual) value written into 
the digital output register. 



isb 



A 2-word integer array to which the subroutine status is 
returned . 

The isb array has the standard meaning described in Section 16.4.1. 

When the function form of the call is used, the value of the function 
is the same as that returned in newval. 



16.4.13 IRDB: Reading Data from an Input Buffer 

The IRDB FORTRAN subroutine or function retrieves data sequentially 
from a buffer that a laboratory peripheral system driver is 
synchronously filling. If no data is available when the call is 
executed, the contents of the next location In the data buffer are 
returned without updating the buffer pointers. The call is Issued as 
follows : 

CALL IRDB (ibuf ,[lval] ) 
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ibuf 

An integer array that was previously specified in a synchronous 
input sampling request (that is, DRS, HIST, or RTS) . 

ival 

A variable that receives the next value in the data buffer. 

When the function form of the call is used, the value of the function 
is the same as that returned in ival. 



16.4.14 LED: Displaying in LED Lights (LPSll only) 

The LED FORTRAN subroutine displays a 16-bit signed binary integer in 
the LED lights. The number is displayed with a leading blank 
(positive number) or minus (negative number) , followed by five 
non-zero-suppressed decimal digits that represent the magnitude of the 
number. LED digits are numbered right to left starting at 1 and 
continuing to 5. The number may be displayed with or without a 
decimal point. The call is issued as follows: 

CALL LED (ival, [idee] , [isb] ) 

ival 

The variable whose value is to be displayed. 

idee 

The position of the decimal point, A value of 1 to 5 specifies 
that a decimal point is to be displayed. All other values 
specify that no decimal point is to be displayed. 



isb 



A 2-word integer array to which the subroutine status is 
returned. 



The isb array has the standard meaning described in Section 16.4.1. 
For example, the following call: 

CALL LED (-55,2) 
would cause -0005.5 to be displayed in the LED lights. 
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16.4.15 LPSTP: Stopping an In-Progress Synchronous Function 

The LPSTP FORTRAN subroutine selectively stops a single synchronous 
request. The call is issued as follows: 

CALL LPSTP (ibuf) 

ibuf 

An integer array that specifies a buffer that was previously 
specified in a synchronous initiation request. 



16.4.16 PUTD: Putting a Data Item into an Output Buffer 

The PUTD FORTRAN subroutine puts data sequentially into a buffer that 
a laboratory peripheral system driver is synchronously emptying. If 
no free space is available, no operation is performed. The call is 
issued as follows: 

CALL PUTD (ibuf,ival) 

ibuf 

An integer array which was previously specified in a synchronous 
output request (SDO or SDAC) . 



ival 



A variable whose value is to be placed in the next free location 
in the data buffer. 



16.4.17 RELAY: Latching an Output Relay (LPSll only) 

The RELAY FORTRAN subroutine opens or closes the LPSll relays. The 
call is issued as follows: 

CALL RELAY ( i rel , i State ,[ isb] ) 

irel 

Which relay is to be opened or closed (0 for relay one, 1 for 
relay two) . 



istate 



Whether the relay is to be opened or closed. If istate equals 0, 
the relay is to be opened. Otherwise, it is to be closed. 



Lsb 



A 2-word integer array to which the subroutine status is 
returned . 

The isb array has the standard meaning described in Section 16.4.1. 
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16.4.18 RTS: Initiating Synchronous A/D Sampling 

The RTS FORTRAN subroutine reads one or more A/D channels at precisely 
timed intervals, with or without auto gain-ranging. The auto 
gain-ranging algorithm (LPSll only) causes the channels to be sampled 
at the highest gain at which saturation does not occur. 

Sampling can be started when the interface subroutine is called or 
when a specified digital input point is set. A digital output point 
can optionally be set when sampling is started. Sampling can be 
terminated by a program request (stop-in-progress request or kill 
I/O) , the clearing of a digital input point, or the collection of a 
specified number of buffers of data. 

All input is double buffered with respect to the user task. Each time 
a half buffer of data has been collected, the user task is notified 
(by the setting of an event flag) that data is available to be 
processed while the driver fills the other half of the buffer. Data 
can be sequentially retrieved from the data buffer with the IRDB 
routine (see Section 16.4.12), or the ADJLPS routine (see Section 
16.4.5) can be used in conjunction with direct access to the input 
data. The call is issued as follows: 

CALL RTS (ibuf,ilen,imode, irate, iefn, ichan,nchan,isb, 
[nbuf] , [istart] , [istop] ) 



ibuf 



An integer array that is to receive the converted data values. 



lien 



The length of ibuf (must be even and greater than or equal to 6) 



imode 



The start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values as 
shown below: 



Function 
Selection 
Value 

128 

64 

32 

16 

8 



Meaning 
Start on digital input point set 
Set digital output point at start 
Stop on digital input point clear 
Stop on number of buffers 
Auto gain-ranging (LPSll only) 
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irate 



A 2-word integer array that specifies the time interval between 
A/D samples. The first word specifies the interval unit as 



follows: 




irate(l) 


Unit 


1 


Real-time clock ticks 


2 


Milliseconds 


3 


Seconds 


4 


Minutes 



iefn 



The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 



The number of the event flag that is to be set each time a half 
buffer of data has been collected. 



ichan 



The starting A/D channel of the block of channels to be sampled 
synchronously (must be between and 63 for LPSll and between 
and 15 for ARll) . 



nchan 



isb 



The number of A/D channels to be sampled (must be between 1 and 
64 for LPSll and between 1 and 16 for ARll) . 



A 2-word integer array to which the subroutine status is 
returned . 



nbuf 



The number of buffers of data that are to be collected. It is 
needed only if a function selection value of 16 has been added 
into imode. 



istart 



The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. Points are numbered from to 
15, allowing a maximum of 16 points to be specified. 



istop 



The digital input point number to be used to stop sampling. It 
is needed only if a function selection value of 32 has been added 
into imode. 



16-24 



LABORATORY PERIPHERAL SYSTEMS DRIVERS 

The values listed for ichan and nchan above are the maximum allowable 
for each of the devices. In practice, they are constrained by the 
number of channels available as specified during SYSGEN. 

The isb parameter has the standard meaning described in Section 
16.4.1. 

When sampling is in progress, the first word of the isb array is and 
the second word contains the number of data values currently in the 
buffer. 



16.4.19 SDAC: Initiating Synchronous D/A Output 

The SDAC FORTRAN subroutine writes data into one or more external D/A 
converters at precisely timed intervals. Output may be started and 
stopped as for RTS (see Section 16.4.18), and all input is double 
buffered with respect to the user task. One full buffer of data must 
be available when synchronous output is initiated. 

After SDAC has initiated output and the specified event flag has been 
set to notify the task that free buffer space is available, the PUTD 
routine (see Section 16.4.16) may be used to put data values 
sequentially into the output data buffer. The ADJLPS routine (see 
Section 16.4.5) may be used in conjunction with direct access to the 
output data buffer. The SDAC call is issued as follows: 

CALL SDAC (ibuf,ilen,imode, irate, iefn, ichan, nchan, isb, 
[nbuf] , [istart] , [istop] ) 

ibuf 

An integer array that contains the output data values, 

ilen 

The length of ibuf (must be even and greater than or equal to 6). 



imode 



The_ start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values as 
shown below: 

Function 
Selection 
Value Meaning 

128 Start on digital input point set 

64 Set digital output point at start 

32 Stop on digital input point clear 

16 Stop on number of buffers 
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irate 

A 2-word integer array that specifies the time interval between 
D/A outputs. The first word specifies the interval units as 



follows: 




irate(l) 


Unit 


1 


Real-time clock ticks 


2 


Milliseconds 


3 


Seconds 


4 


Minutes 



The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 



iefn 



The number of the event flag that is to be set each time a half 
buffer of data has been output. 



ichan 



The starting D/A channel of the block of channels to be written 
into synchronously (must be between and 9 for LPSll, and be 
or 1 for ARll) . 



nchan 



isb 



The number of D/A channels to be written into (must be between 
and 10 for LPSll, and be 1 or 2 for ARll). 



A 2-word integer array to which the subroutine status is 
returned , 



nbuf 



The number of buffers of data to be output. It is needed only if 
a function selection value of 16 has been added into imode. 



istart 



The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. Points are numbered from to 
15, allowing a maximum of 16 points to be specified. 
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istop 

The digital input point number to be used to stop sampling. It 
is needed only if a function selection value of 32 has been added 
into imode. 

The isb array has the standard meaning described in Section 16.4.1. 

When sampling is in progress, the first word of the isb array is and 
the second word contains the number of free positions in the buffer. 

16.4.20 SDOs Initiating Synchronous Digital Output 

The SDO FORTRAN subroutine writes data qualified by a mask word into 
the digital output register at precisely timed intervals. Sampling 
may be started and stopped as for RTS (see Section 16.4.18) and all 
input is double buffered with respect to the user task. One full 
buffer of data must be available when output is initiated. 

After SDO has initiated output, and the specified event flag has been 
set to notify the task that free buffer space is available, the PUTD 
routine (see Section 15.4.16) may be used to put data values 
sequentially into the output data buffer. The ADJLPS routine (see 
Section 16.4.5) may be used in conjunction with direct access to the 
output data buffer. The SDO call is issued as follows: 

CALL SDO (ibuf,ilen, imode, irate, iefn,imask, isb, [nbuf] , 
[istart] , [istop] ) 

ibuf 

An integer array that contains the digital output values. 

ilen 

The length of ibuf (must be even and greater than or equal to 6). 



imode 



The start, stop, and sampling mode. Its value is encoded by 
adding together the appropriate function selection values as 
shown below: 

Function 
Selection 
Value Meaning 

128 Start on digital input point set 

64 Set digital output point at start 

32 Stop on digital input point clear 

16 Stop on number of buffers 
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irate 



A 2-word integer array that specifies the time interval between 
digital outputs. The first word specifies the interval units as 
follows: 

irate(l) Unit 

1 Real-time clock ticks 

2 Milliseconds 

3 Seconds 

4 Minutes 

The second word specifies the interval magnitude as a 16-bit 
unsigned integer. 



iefn 



The number of the event flag that is to be set each time a half 
buffer of data has been output. 



imask 



isb 



The digital output points that are to be written. It may be 
conveniently specified as an octal constant. 



A 2-word integer array to which the subroutine status is 
returned . 



nbuf 



The number of buffers of data to be output. It is needed only if 
a function selection value of 16 has been added into imode. 



istart 



The digital input point number to be used to trigger sampling 
and/or the digital output point number to be set when sampling is 
started. It is needed only if a function selection value of 128 
or 64 has been added into imode. Points are numbered through 
15, allowing a maximum of 16 points to be specified. 

istop 

The digital input point number to be used to stop sampling. It 
is needed if a function selection value of 32 has been added into 
imode . 

The isb parameter has the standard meaning described in Section 

16.4.1. 

When sampling is in progress, the first word of the isb array is and 
the second word contains the number of free positions in the buffer. 
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16.5 STATUS RETURNS 

The error and status conditions listed in Table 16-8 are returned by 
the Laboratory Peripheral System drivers described in this chapter. 



Table 16-8 
Laboratory Peripheral Systems Status Returns 



Code 


Reason 


IS. sue 


Successful completion 




The operation specified in the QIO directive was 
completed successfully. The second word of the 
I/O status block can be examined to determine the 
number of data values processed. 


IS.PND 


I/O request pending 




The operation specified in the QIO directive has 
not yet been completed. 


IE. ABO 


Operation aborted 




The specified I/O operation was canceled (by 
lO.KIL or lO.STP) while in progress. 


IE. BAD 


Bad parameter 




An illegal specification was supplied for one or 
more of the device-dependent QIO parameters (words 
6-11). The second I/O status word is filled with 
Os. 


IE. BYT 


Byte-aligned buffer specified 




Byte alignment was specified for a data buffer but 
only word alignment is legal for Laboratory 
Peripheral Systems. Alternatively, the length of 
a buffer is not an even number of bytes. 


lE.DAO 


Data overrun 




For Laboratory Peripheral Systems, the driver 
attempted to get a value from the user buffer when 
none was available or attempted to put a value in 
the user buffer when no space was available. 


lE.DNR 


Device not ready 




The physical device unit specified in the QIO 
directive was not ready to perform the desired I/O 
operation. For Laboratory Peripheral Systems, 
this code is returned if a device time-out occurs 
while a function is in progress. The second I/O 
status word contains the number of free positions 
in the buffer, as appropriate. 



(continued on next page) 
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Table 16-8 (Cont.) 
Laboratory Peripheral Systems Status Returns 



Code 


Reason 


lE.IEF 


Invalid event flag number 




An invalid event flag number was specified in a 




synchronous function. 


lE.IFC 


Illegal function 




A function code was included in an I/O request 
that is illegal for the LPSll or ARll. 


IE. NOD 


Insufficient buffer space 




Dynamic storage space has been depleted, and there 
is insufficient buffer space available to allocate 
a secondary control block for a synchronous 
function. 


lE.OFL 


Device off line 




The physical device unit associated with the LUN 
specified in the QIO directive was not on line. 
When the system was booted, a device check 
indicated that this physical device unit was not 
in the configuration. 


lE.ONP 


Option not present 




An option dependent function or subfunction was 
requested, and the required feature was not 
specified at system generation. For example the 
gain-ranging option or D/A option is not present. 
The second I/O status word contains 0. 


lE.PRI 


Privilege violation 




The task which issued the request was not 
privileged to execute that request. For 
Laboratory Peripheral Systems, a checkpointable 
task attempted to execute a synchronous sampling 
function. 


lE.RSU 


Resource in use 




A resource needed by the function requested in the 
QIO directive was being used (see Section 16.5.1). 


lE.SPC 


Illegal address space 




The buffer specified for a read or write request 
was partially or totally outside the address space 
of the issuing task. Alternately a byte count of 
was specified. The second I/O status word 
contains 0. 



FORTRAN interface values for these status 
Section 16.5.4. 



returns are presented in 
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16.5.1 lE.RSU 

lE.RSU is returned if a function requests a resource that is currently 
being used. The requesting task may repeat the request at a later 
time or take any alternative action required. 

Because certain functions do not need such resources, they never cause 
this code to be returned. Other functions return this code under the 
following conditions: 

Function When lE.RSU Is Returned 

lO.SDO One or more specified digital output bits are in 
use. 

10. ADS Digital output point (if specified) is in use. 

10. HIS Digital output point (if specified) is in use. 

lO.MDA Digital output point (if specified) is in use. 

lO.MDI Digital output point (if specified) or digital 
input points to be sampled are in use. 

lO.MDO Digital output point (if specified) or output bits 
to be written are in use. 

The following components of the Laboratory Peripheral Systems are each 
considered a single resource: 

Resource When Shareable 

The A/D Converter Always shareable 
and clock 

Each bit in the Never shareable. 

digital output 

register 

Each bit in the Always shareable when used by lO.SDI 

digital input or for start/stop conditions (specified 

register in subfunction modifier bits) , even when 

in use by another function; when 
specified by a synchronous digital input 
function, not shareable with another 
such function 

Each resource is allocated on a first-come-first-served basis. (That 
is, when a conflict arises, the most recent request is rejected with a 
status of lE.RSU) . 



16.5.2 Second I/O Status Word 

On successful completion of a function specified in a QIO macro call, 
the IS. sue code is returned to the first word of the I/O status block. 

Table 16—9 lists the contents of the second word of the status block 
on successful completion for each function. 
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Table 16-9 
Returns to Second Word of I/O Status Block 



Successful 




Function 


Contents of Second Word 


lO.KIL 


Number of data values before I/O was canceled 


10. LED 





lO.REL 





lO.SDI 


Masked value read from digital input register 


lO.SDO 


Updated value written into digital output register 


10. ADS 


Number of data values remaining in buffer 


10. HIS 


Number of data values remaining in buffer 


lO.MDA 


Number of free positions in buffer 


lO.MDI 


Number of data values remaining in buffer 


lO.MDO 


Number of free positions in buffer 


lO.STP 






When IE. BAD is returned, the second I/O status word contains 0/ 
Laboratory Peripheral Systems drivers return the IE. BAD code under the 
following conditions: 



Function 



When IE. BAD is Returned 



lO.REL 

10. ADS 
lO.MDA 

10. HIS 
lO.MDI 
lO.MDO 



Relay number not or 1 

No I/O status block, illegal digital I/O point 
number, or illegal channel number 

No I/O status block or illegal 
digital I/O point number 



16.5.3 10. ADS and ADC Errors 

While 10. ADS or the ADC FORTRAN subroutine is converting a sample, two 
error conditions may arise. Both of these conditions are reported to 
the user by placing illegal values in the data buffer. A -1 
(177777(8) is placed in the buffer if an A/D conversion does not 
complete within 30 microseconds. A -2 (177776(8) is placed in the 
buffer if an error occurs during an A/D conversion (LPSll only) . 
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16.5.4 FORTRAN Interface Values 

The values listed in Table 16-10 are returned in FORTRAN subroutine 
calls. 



Table 16-10 
FORTRAN Interface Values 



Status Return 


FORTRAN Value 


IS. sue 


+01 


IS.PND 


+00 


IE. ABO 


+ 315 


lE.ADP 


+101 


lE.ALN 


+334 


IE. BAD 


+ 301 


IE. BYT 


+ 319 


lE.DAO 


+ 313 


lE.DNR 


+303 


lE.IEF 


+100 


lE.IFC 


+302 


lE.ILU 


+ 99 


IE. NOD 


+323 


lE.OFL 


+365 


lE.ONP 


+305 


lE.PRI 


+316 


lE.RSU 


+317 


lE.SDP 


+102 


lE.SPC 


+306 


lE.ULN 


+08 


lE.UPN 


+04 



16.6 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the Laboratory Peripheral Systems 
drivers described in this chapter. 



16.6.1 The LPSll/ARll Clock and Sampling Rates 

The basic real-time clock frequency (count rate) for all synchronous 
functions is always lOKHz. Device characteristics word 4 contains a 
16-bit buffer preset value — set dynamically or at system generation, 
that controls the rate of "ticks" (that is, the rate at which the 
clock interrupts) . The quotient that results when this value is 
divided into lOKHz is the rate of "ticks." For example, if this value 
is 2, the "tick" rate is 5KHz. The user can use a Get LUN Information 
system directive to examine the value and a SET /BUF MCR function to 
modify it while the system is running. 
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The ticks parameter in a synchronous function specifies the number of 
"ticks" between samples or data transfers. The value of ticks is a 
16-bit number. Thus 65,536 discrete sampling frequencies are possible 
for each of 65,536 different "tick" rates. This provides a maximum 
single-channel sample rate of 1 sample every 100 microseconds 
(possible in hardware but impractical in software) and a minimum of 1 
sample every 429,495 seconds. A single-channel rate greater than 2KHz 
is possible, but not recommended. 

The figures below represent initial timing tests run under RSX-llM. 
It should be noted that no computation was performed on the data other 
than continuously removing it from or inserting it into the data 
buffer. 

The following data is for the LPSll on a PDP-11/40 with memory 
management, with no gain-ranging option, and with digital I/O option. 

Analog rates: 

1 request for 1 channel at 2.5KHz 

1 request for 2 channels at 2.0KHz (aggregate 4KHz) 

2 requests for 1 channel at 2.0KHz (aggregate 4KHz) 
Digital rates: 

1 request for 2 channels at 2.5KHz (aggregate 5KHz) 

The following data is for the ARll on a PDP-11/40 with no memory 
management, no digital I/O option, and no unipolar sampling. 

Analog rates: 

1 request for 1 channel at 3.3KHz 

1 request for 2 channels at 2.5KHz (aggregate S.OKHz) 

2 requests for 1 channel at 2.5KHz (aggregate S.OKHz) 
Digital rate: 

2 requests for 2 channels at 3.3KHz (aggregate 6.6KHz) 



16.6.2 Importance of the I/O Status Block 

An I/O status block must be specified with every synchronous function. 
If the first I/O status word is nonzero, the request has been 
terminated and the value indicates the reason for termination. 
Otherwise, the request is in progress, and the second I/O status word 
contains the number of data values remaining in the buffer (or the 
number of free positions in the buffer for lO.MDA and lO.MDO) . 
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lOSB: 


.BLKW 


2 


CURPT: 


.WORD 


BUFFER 


LSTPT: 


.WORD 


BUFFER+n 


FSTPT: 


.WORD 


BUFFER 



16.6.3 Buffer Management 

The buffer unload protocol for synchronous input functions is 
described below. The user constructs a 5-word block that contains the 
following : 

I/O STATUS DOUBLE-WORD 

ADDRESS OF BUFFER 

ADDRESS OF END OF BUFFER 

ADDRESS OF BUFFER 

Two of these words are required by the driver (I/O status block) and 
the remaining three by the user to unload data values from the buffer. 

The user then issues the I/O request with the appropriate parameters 
and the address of the above block as the I/O status block. The QIO 
directive Os both I/O status words to initialize them. 

If the driver accepts the request, it sets up a write pointer to the 
first word in the user buffer. Thus, the user has a buffer read 
pointer and the driver has a buffer write pointer. The user and the 
driver share the second I/O status word, which is the number of data 
words in the buffer that contain data. 

Each time the driver attempts to put a sample value into the buffer, 
it increments the second I/O status word and compares the result with 
the size of the buffer. If the result is greater, buffer overrun has 
occurred and the request is terminated. Otherwise, the value is 
stored in the buffer at the address specified by the driver's write 
pointer and the write pointer is updated. 

If the value stored in the user buffer fills half of the buffer, the 
event flag specified in the I/O request is set in order to notify the 
user that a half buffer of data is available to be processed. Each 
time the user task is awakened, it should execute the following code: 



5$: 
10$: 



20$; 
30$; 

40$: 



CLEF$S 

TST 

BEQ 

MOV 

DEC 

ADD 

CMP 

BLOS 

MOV 

Process 

BR 

TSTB 

BNE 

WTSE$S 

BR 

Determi 



#EFN 
IOSB+2 
30$ 

@CURPT,RO 
IOSB+2 
#2, CURPT 
CURPT, LSTPT 
20$ 

FSTPT, CURPT 
data value 
10$ 
lOSB 
40$ 
#EFN 
5$ 
ne reason for t 



CLEAR EFN 

ANY DATA IN BUFFER? 

IF EQ NO 

GET NEXT VALUE FROM BUFFER 

REDUCE NUMBER OF ENTRIES 

UPDATE BUFFER READ POINTER 

END OF BUFFER? 

IF LOS NO 

RESET BUFFER READ POINTER 

TRY AGAIN 

REQUEST TERMINATED? 

IF NE YES 

WAIT FOR EFN 



ermination 
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For lO.MDA and lO.MDO, this protocol differs slightly. The user task 
maintains a write pointer and the driver a read pointer. The entire 
buffer must be full when the request is executed. 



16.6.4 Use of A^JLPS for Input and Output 

The following FORTRAN example illustrates the proper protocol for 
using ADJLPS for synchronous input and output. 

Synchronous input: 

DIMENSION IBF(1004) ,IERR(2) ,INTVL(2) 
C 

C INITIATE SYNCHRONOUS A/D SAMPLING, 
C 

INTVL(1)=2 

INTVL(2)=5 

CALL RTS(IBF,1004,160,INTVL,IEFN,6,6,IERR,50,14,15) 
C 

C INITIALIZE HALF BUFFER INDEX 
C 

INDX=4 
C 

C WAIT FOR HALF BUFFER OF DATA 
C 

10 CALL WAITFR(IEFN) 
C 

C CLEAR EVENT FLAG 
C 

15 CALL CLREF(IEFN) 
C 

C PROCESS HALF BUFFER OF DATA 
C 

SUM=0 

DO 20 1=1,500 

SUM=SUM+CVSWG(IBF{I+INDX) ) 
20 CONTINUE 

AVERG=SUM/500 
C 

C FREE HALF BUFFER FOR MORE DATA 
C 

CALL ADJLPS (IBF, 500) 
C 

C ADJUST BUFFER INDEX 
C 

INDX=INDX+500 

IF(INDX.GE.1004) INDX=4 
C 

C CHECK IF ANOTHER HALF BUFFER OF DATA IS AVAILABLE 
C 

IF(IERR{2) .GE.500 GO TO 15 

IF(IERR(1) .NE.O) GO TO end of sampling 

GO TO 10 
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Synchronous output: 

DIMENSION IBF(1004) ,IERR(2) ,INTVL(2) 
C 

C FIRST BUFFER OF DATA MUST BE AVAILABLE AT START 
C 

C THIS EXAMPLE ASSUMES FIRST BUFFER IS FULL AT START 
C 

C START SYNCHRONOUS DIGITAL OUTPUT FUNCTION 
C 

INTVL(1)=2 

INTVL(2)=5 

CALL SDO(IBF,1004,160,INTVL,IEFN,MASK,IERR,50,14,15) 
C 

C INITIALIZE HALF BUFFER INDEX 
C 

INDX=4 
C 

C WAITFOR ROOM IN BUFFER 
C 

10 CALL WAITFR(IEFN) 
C 

C CLEAR EVENT FLAG 
C 

15 CALL CLREF(IEFN) 
C 

C CALCULATE VALUES TO PUT IN BUFFER 
C 

X=(Y+2)*Z 

DO 20 1=1,500 

IBF(I+INDX)=X**5/A 
20 CONTINUE 
C 

C SIGNIFY ANOTHER HALF BUFFER IS FULL 
C 

CALL ADJLPS(IBF,500) 
C 

C ADJUST BUFFER INDEX 
C 

INDX=INDX+500 

IF(INDX.GE.1004) INDX=4 
C 

C CHECK IF ANOTHER HALF BUFFER IS EMPTY 
C 

IF(IERR(2) .GE.500) GO TO 15 

IF{IERR(1) .NE.O) GO TO end of sampling 

GO TO 10 



NOTE 

In both of the examples above, care is taken to ensure 

that the program stay "in sync" with the driver. If the 

program "loses" its position with respect to the driver, 

the function must be stopped and restarted, since this is 
the only way to recover. Caution should be exercised to 

ensure that the program sequence above be used to avoid a 
possible loss of data. 
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QIO DPB format: 

QIO$C lO.SAO, . . . ,<chn,vout> 

chn 

The output channel number. 

vout 

The output voltage representation. 

Output voltage varies linearly with the binary input to the channel, 
where to plus 10 volts (+10v.) is represented by integers from to 
1023. 

Return Status: 

IS. sue - Function submitted for output to controller. 

IE. MOD - Nonexistent D/A channel was specified. 
The second I/O status word is 0. 



18.3.4 Momentary Digital Output - Multi-Point 

This function provides the capability of pulsing a field of up to 16 
momentary (single-shot) digital output points. Fields must be aligned 
on module boundaries. 

QIO DPB format: 

QIO$C lO.MSO, . . . ,<opn,dp> 



opn 



dp 



The starting digital output point number. Point number must be 
aligned on a module boundary (that is, must be a multiple of 16). 



The 16-bit mask. One point is pulsed corresponding to each bit 
set in the mask word. 



Return Status: 

IS. sue - Function submitted for output to the controller. 

IE. MOD - Invalid starting point number specified. Point is 
nonexistent or not aligned on a module boundary. 



CHAPTER 17 
PAPER TAPE READER/PUNCH DRIVERS 



17.1 INTRODUCTION 

The RSX-llM/M-PLUS paper tape reader/punch drivers support the PCll 
paper tape reader/punch and the PRll paper tape reader. The PCll is a 
high-speed reader/punch capable of reading 8-hole, unoiled, perforated 
paper tape at 300 characters per second, and punching tape at 50 
characters per second. The PRll has the same characteristics as those 
of the paper tape reader portion of the PCll. All transfers are image 
mode only, with no interpretation of data. 



17.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the GET LUN INFORMATION system 
directive (the first characteristics word) contains the following 
information for paper tape devices. A bit setting of 1 indicates that 
the described characteristic is true for these devices. 



Bit Setting Meaning 






1 


1 





2 





3 





4 





5 





6 





7 





8 





9 





10 





11 






Record-oriented device 

Carriage-control device 

Terminal device 

File-structured device 

Single-directory device 

Sequential device 

Mass storage device 

User-mode diagnostics supported 

Device supports 22-bit direct addressing 

Unit software write-locked 

Input spooled device 

Output spooled device 
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Bit Setting 



Meaning 



12 





13 





14 





15 






Pseudo device 

Device mountable as a communications channel 
Device mountable as a FILES-11 volume 
Device mountable 



Words 3 and 4 of the buffer are undefined; word 5 indicates the 
default buffer size, which is 64 bytes for paper tape devices. 



17,3 QIO MACRO 

Table 17-1 lists the standard functions of the QIO macro that are 
valid for the paper tape reader/punch. 



Table 17-1 
Standard QIO Functions for the Paper Tape Reader/Punch 



Format 


Function 


QIO$C 


10. ATT,.. 


• 


Attach device 


QIO$C 


lO.DET,. . 


• 


Detach device 


QIO$C 


lO.KIL, . . 


• 


Cancel I/O requests 


QIO$C 


lO.RLB, .. 


. ,<stadd ,size> 


READ logical block (reader only) 


QIO$C 


lO.RVB,.. 


. ,<stadd ,size> 


READ virtual block (reader only) 


QIO$C 


lO.WLB,.. 


. ,<stadd,size> 


WRITE logical block (punch only) 


QIO$C 


lO.WVB,.. 


. ,<stadd,size> 


WRITE virtual block (punch only) 



stadd 



The starting address of the data buffer 
boundary) 



(may be on 



byte 



size 



The data buffer size in bytes (must be greater than 0) 



lO.KIL never cancels an in-progress read request. In-progress write 
requests are canceled only when the punch driver is waiting for the 
punch to become ready at the start of a transfer. 

The paper tape drivers support no device-specific functions. 
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17.4 STATUS RETURNS 

Table 17-2 lists error and status conditions that are returned by the 
paper tape reader/punch drivers. 



Table 17-2 
Paper Tape Reader/Punch Status Returns 



Code 


Reason 


IS. sue 


Successful completion 




The operation specified in the QIC directive was 
completed successfully. The second word of the I/O 
status block can be examined to determine the number 
of bytes processed. If the operation involved reading 
or writing. 


IS.PND 


I/O request pending 




The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 


IE. ABO 


Operation aborted 




The I/O request was cancelled while in progress or 
while still in the I/O queue. 


lE.DAA 


Device already attached 




The physical device unit specified in an 10. ATT 
function was already attached by the issuing task. 
This code indicates that the issuing task has already 
attached the desired physical device unit, not that 
the unit was attached by another task. 


lE.DNA 


Device not attached 




The physical device unit specified in an lO.DET 
function was not attached by the issuing task. This 
code has no bearing on the attachment status of other 
tasks. 


lE.DNR 


Device not ready 




The reader and punch drivers return this code when a 
time-out occurs. The reader driver also returns this 
code when an error condition (see Section 17.4.1) is 
encountered before the initiation of the first 
transfer after an ATTACH command has been issued. 


IE. EOF 


End-of-file encountered 




The reader driver encountered an error condition (see 
Section 17.4.1) at a time other than the initiation 
of the first read after a valid ATTACH command. The 
second word of the I/O status buffer contains a count 
of bytes successfully read before the error condition 
was encountered. 



(continued on next page) 
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Code 



lE.IFC 



lE.OFL 



lE.SPC 



lE.VER 



Table 17-2 (Cont.) 
Paper Tape Reader/Punch Status Returns 



Reason 



Illegal function 

An illegal function code was specified in an I/O 
request that is not legal for the respective paper 
tape drivers. 

Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive was not on line. When 
the system was booted, a device check indicated that 
this physical device unit was not in the 
configuration. 

Illegal address space 

The buffer specified for a read or write request was 
partially or totally outside the address space of the 
issuing task. Alternatively, a byte count of was 
specified . 

Unrecoverable hardware error (punch only) 

The punch driver encountered an error condition (see 
Section 17.4.1) at a time other than the initiation 
of a transfer. Section 17.4.2 describes the action 
of the punch driver when an error condition is 
encountered upon the initiation of a transfer. 



17.4.1 Error Conditions 

There are four error conditions that are indistinguishable to the 
paper tape drivers. These conditions are: 

• No tape 

• Reader off line 

• Power low 

• Hardware malfunction 



17.4.2 Ready Recovery 

When the punch driver encounters an error condition upon 
initiation of a transfer, the following message is displayed; 



the 



*** PPn: 



— NOT READY 



The unit number of the paper tape punch that is not ready. 
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This message is repeated every 15 seconds until the error condition is 
corrected, or until the I/O request is canceled. When the error 
condition has been corrected, the transfer will begin within 1 second. 



17.5 PROGRAMMING HINTS 

This section contains information on important programming 
considerations relevant to users of the paper tape drivers described 
in this chapter. 



17.5.1 Special Action Resulting from Attach and Detach 

When an Attach or Detach is issued to the punch, the punch driver 
initiates a transfer of 170 (decimal) nulls. Upon the first read 
after an attach to the reader, all nulls preceding the first non-null 
character on the tape are read and discarded by the reader driver. 



17.5.2 Reading Past End-of-Tape 

When the reader driver reads past the physical end-of-tape, it 
normally generates at least two incorrect data bytes. These bytes are 
included in the byte count returned by the driver. User software that 
does not prevent reads past the physical end-of-tape should discard at 
least the last six characters in the buffer when IE. EOF is returned by 
the driver. 
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18.3.5 Bistable Digital Output - Multi-Point 

This function provides the capability of setting or resetting a field 
of up to 16 bistable digital output points. Fields must be aligned on 
a module boundary. 

QIC DPB format: 

QIO$C lO.MLO, . . . ,<opn,pp,dp> 



opn 



PP 



The starting digital output point number. Point number must be 
aligned on a module boundary (that is, must be a multiple of 16). 



The 16-bit mask. 



dp 

The data pattern. 

A bit is set in the mask word for each point that may change state. 
The state of points corresponding to reset mask bits is unaltered. 
When the mask bit is set, the output is "closed" if the data bit is 
set and "open" if the data bit is clear. 

Return Status: 

IS. sue - Function submitted for output to the controller. 

IE. MOD - Invalid starting point number specified. Point does not 
exist or is not aligned on a module boundary. 



18.3.6 Unsolicited Interrupt Processing 
Unsolicited interrupts consist of the following: 

1. Digital interrupts 

2. Counter interrupts 

3. Remote terminal input 

4. Hardware errors 

Based on the type of interrupt, the driver may dispose of the 
interrupt data in one or more of the following ways: 

1. The data may be furnished to a task that has issued a request 
to monitor such information continually. This alternative is 
not available in the DSS/DRS driver. 

2. A task may be activated by a specific input. That is, a 
dormant task can be requested to run, or an event flag may be 
set if the task is currently active. 
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INDUSTRIAL CONTROL SUBSYSTEMS 



18.1 INTRODUCTION 

This chapter describes RSX-llM drivers for two process I/O subsystems: 
the ICS/ICRll and the DSS/DRSll. (Driver support for these I/O 
subsystems is not provided in RSX-llM-PLUS systems.) 

ICSll and ICRll are local and remote process I/O subsystems, 

respectively. They operate under program control as devices capable 

of interrogating digital and analog input, and driving digital and 
analog output. 

DSSll and DRSll are digital input and output subsystems, respectively. 
Under program control they drive digital output and interrogate 
digital input. 



18.1.1 Hardware Configuration 

A single ICS or ICR controller can handle up to 16 I/O modules in any 
configuration; a module contains 16 bits of input or output data, 
providing a total of 256 digital points. Up to 12 ICR or ICS units 
are supported. The ICS/ICR driver is tailored to the user's needs, 
interactively, through the SYSGEN (System Generation program) 
dialogue. The driver is capable of handling any combination of ICR or 
ICS controllers installed on a single system. 

The DSSll provides 49 optically isolated inputs, including 48 
nonbuffered, sense-data inputs and one interrupt input. The DRSll 
provides 48 open-collector, buffered outputs plus one interrupt input. 
The DSS/DRS driver is shaped to the user's system configuration in the 
SYSGEN dialog. The driver supports up to 16 DSSll and/or DRSll 
modules. 



18.1.1.1 ICS/ICR Address Assignments - Each ICRllA Unibus interface 
or ICSll file box must be configured at SYSGEN time for individually 
addressable interrupt vectors. Control and Status Registers (ICSR) , 
and module Address Registers (ICAR) , as shown in Table 18-1. 
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Table 18-1 
ICS/ICR Address Assignments 



ICS/ICR Unit No. 


Module Addresses 


ICSR/ICAR Addresses 


Interrupt Vectors 





171000-171036 


171770-171776 


234-236 


1 


171040-171076 


171760-171766 


xxx-xxx+2 


2 


171100-171136 


171750-171756 


XXX+4-XXX+6 


3 


171140-171176 


171740-171746 


xxx+lO-xxx+12 


4 


171200-171236 


171730-171736 


XXX+14-XXX+16 


5 


171240-171276 


171720-171726 


XXX+20-XXX+22 


6 


171300-171336 


171710-171716 


XXX+24-XXX+26 


7 


171340-171376 


171700-171706 


XXX+30-XXX+32 


10 


171400-171436 


171670-171676 


XXX+34-XXX+36 


11 


171440-171476 


171660-171666 


XXX+40-XXX+42 


12 


171500-171536 


171650-171656 


XXX+44-XXX+46 


13 


171540-171576 


171640-171646 


XXX+50-XXX+52 



NOTES 



nnnnnfi = Control and Status Register 
nnnnn4 = Address Register 

Additional controllers are assigned 
addresses above 300. 



vector 



18.1.1.2 DSS/DRS Address Assignments - Unlike the ICS/ICR subsystem, 
DSS/DRS devices are not restricted to specified bus addresses. 
However, the following constraints apply: 

1. All DSSll modules must occupy a contiguous set of bus 
addresses. 

2. All DRSil modules must occupy a contiguous set of bus 
addresses. 

3. The total number of DSSll and DRSll modules may not exceed 
16. 

4. If both module types are installed in a system, the DRSll 
must occupy the lower set of bus and interrupt-vector 
addresses. 

5. Bus request priority is BR4. 
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18.1.1.3 Supported ICS/ICR I/O Modules - The following modules, all 
optional, are supported by the ICS/ICR driver: 

D/A Converters 

IDA-OA - 4-channel digital-to-analog converter 

A/D Converters 

lAD-IA - 8-channel wide-range differential analog-to-digital 

converter 
IMX-IA - 16-channel flying capacitor relay multiplexer 

Counters 

IDC-IC - 16-bit binary counter 

Bistable Digital Outputs 

IDC-OA - D/C flip-flop driver 

lAC-OA - A/C flip-flop driver 

IRL-OA - Bistable relay output 

IRL-OB - Flip-flop relay output 

Momentary Digital Output 

IDC-OB - D/C momentary driver 
lAC-OB - A/C momentary driver 

Digital Inputs (Noninterrupting) -'- 

IDC-IA - D/C voltage sense input 
IDC-ID - D/C voltage input module 
lAC-IA - A/C voltage input module 

Digital Inputs (Interrupting) 

IDC-IB - D/C voltage interrupt input 
lAC-IB - A/C voltage interrupt input 

Terminal Input/Output 

110 CPS Remote Terminal Interface to ICRll 



18.1.2 Alternate ICSll Support 

The ICSll Industrial Control Subsystem is supported either by the 

UDCll or ICS/ICRll device driver. If the system does not have an 

ICRll controller, and if a driver of minimum size is required, then 

UDCll support should be considered. The hardware requirements for 
such support are as follows: 

1. Each file box must be assigned to the same interrupt vector 
address (normally 234) . 

2. The control and status register within each file box must 
appear at the same address within the I/O page (normally 



1. Note that noninterrupting input modules are accessed directly by a 
task. Hence, while FORTRAN interface routines are available, no 
support for such modules is included in the driver. 
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If support of the lAD-IA A/D converter is required, the following 
module addressing and installation conventions are imposed: 

1. Each lAD-IA converter and associated IMX-IA relay 
multiplexers are assigned a fixed block of 120 logical 
channel numbers. No more than 32 lAD-IA converters may be 
installed in a single system. Based on this convention, A/D 
converter occupies channels 0-119, A/D converter 1 occupies 
120-239, and so forth. 

2. Regardless of the actual number of IMX-IA multiplexers 
installed, each converter preempts a block of eight 
contiguous module slots. 

3. The slots reserved for all A/D converters and multiplexers 
must occupy a block of contiguous module slots. 

If necessary, Field Service personnel can make the vector and address 
changes. Assuming the hardware configuration is correct, the user can 
implement the desired UDCll software support by answering in the 
affirmative all SYSGEN questions relating to the UDCll. 

If the additional ICS/ICR-11 driver features are required (at a 
commensurate increase in the memory requirements), then each ICSll 
file box must be configured for individually addressable interrupt 
vectors and control status registers. This change can be performed by 
Field Service personnel. The necessary software support is 
incorporated by answering in the affirmative all SYSGEN questions 
relating to the ICS/ICRll. 

The additional ICSll capabilities provided by the ICS/ICRll driver may 
be summarized as follows: 

1. Multicontroller , parallel operation 

2. Increased A/D conversion throughput 

3. Activation of tasks directly from digital interrupts or 
counters 

4. No requirement to install modules of the same type in 
contiguous slots 

Section 18.7 summarizes the software differences between the UDC and 
ICS/ICR drivers in detail. 



18.1.3 Software Support 

Both ICS/ICR and DSS/DRS operations are divided into two categories: 

1. Functions performed directly by any task 

2. Functions requiring driver services 

Direct functions are accomplished through memory references to the 
ICS/ICR or DSS/DRS registers on the I/O page. In a protected system 
any task may gain restricted access to the device registers by linking 
to a global common block that resides within the appropriate physical 
memory limits. Direct functions consist of: 

1. Reading counter modules 

2. Reading any digital input module (DSS) 
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NOTE 

All functions listed in this subsection 
apply to ICS/ICR modules. Those which 
also apply to the DSS and/or DRS 
subsystems are so marked. 

Driver requests are divided into the following categories: 

1. Noninterrupting output functions 

a. Bistable (flip-flop) digital output (DRS) 

b. Analog output 

c. Momentary (single-shot) digital output 

2. Requests for interrupting functions 

a. Analog input 

b. Remote terminal output 

3. Requests for unsolicited interrupts 

a. Digital interrupts (DSS/DRS) 

b. Counter interrupts 

c. Remote terminal input 

d. Remote unit or serial line errors 

With the exception of A/D input and remote terminal output, 
functions are complete upon return to the user's task. 



all 



^"J •,,^^^"i^^V,"°"'"^^'^''"Pting output functions are immediately 
submitted to the controller through a circular buffer that is filled 
at driver level and emptied at interrupt level. A QIC is considered 
successfully completed when the request is inserted in the circular 

The following operations are in this category: 

1. Bistable digital outputs 

2. Analog outputs 

3. Momentary digital outputs 

Interrupting functions are those operations that generate an interrupt 
within some fixed time after initiation. The driver allows a list of 
multiple transactions to be specified in a single QIO. Each 
transaction is initiated in sequence without waiting for the preceding 
interrupt, until either the list is exhausted or all modules of the 
specified type are active. The following operations are in this 
category : 

1. A/D in^^uts 

2. Remote terminal output 
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Unsolicited interrupts may require no initiation by the processor and 
occur at indeterminate intervals. The following functions are in this 
category: 

1. Interrupting digital inputs (DSS/DRS) 

2. Counter modules 

3. Remote terminal input 

4. Error interrupts 

All unsolicited interrupt data, except for errors, may be placed in a 
task-provided circular buffer. On interrupt, an event flag specified 
by the task is set. Such data for each module type is supplied to 
only one task per controller. In addition, the driver will activate 
selected tasks on the occurrence of digital or terminal input 
interrupts. 

Error interrupts are described later in this chapter. 

Terminal support is restricted to passing terminal data between the 
device and a task. The only special character is Control-C (003), 
which may cause a user-specified task to be made active. There is no 
other special processing for terminal I/O except that the parity bit 
is removed. This is similar to the terminal driver function of 
lO.RAL. 

1. MCR is not invoked. 

2, Characters are not echoed, 

3, Carriage control is not performed, 

4, TABS, RUBOUTs, and so forth are not recognized. 

5. Line terminators are not recognized. 

6. Fill characters are not generated. 



18.1.4 UDCll Software Compatibility 

Many of the MACRO and FORTRAN interfaces described in the following 
paragraphs are fully compatible with existing UDCll applications 
software; however, the user should consult Section 18.7 for a summary 
of differences that do exist between UDC and ICS/ICR software. 



18.1.5 Module Addressing Conventions 

Table 18-2 illustrates the relationship between physical slot numbers, 
bus addresses and relative addresses for a given ICS/ICR 
configuration. It is referred to in the following discussion. 

Each A/D converter is assigned a block of 120 channels. The number of 
channels in use within the block depends on the number of multiplexers 
installed. Specifically, each A/D converter has eight channels, and 
each associated multiplexer has 16. 
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Table 18-2 
Sample ICS/ICR Configuration 



Unit: 











Module 


Slot 








Number 


Number 


Type 


Bus Address 


Relative Addresses 


0. 


9. 


D/A converter 


171000 


0-3. 


1. 


10. 


A/D converter 


171002 


0-119. 


2. 


11. 


A/D multiplexer 






3. 


12. 


Counter 


171006 





4. 


13. 


Flip-flop driver 


171010 


0-15. 


5. 


14. 


D/A converter 


171012 


4-7. 


6. 


15. 


Flip-flop driver 


171014 


16.-31. 


7. 


16. 


Counter 


171016 


1. 


8. 


17. 


A/D converter 


171020 


120.-239. 



As noted, a block of 120 relative addresses is reserved for each A/D 
converter. The converter and multiplexer in slots 10 and 11 contain 
channels through 23. The converter in slot 17 contains channels 120 
through 127. An attempt to access a nonexistent channel (for example, 
channel 30 or channel 129) will be rejected by the driver. 

The user should observe that the bistable drivers in slots 13 and 15 
contain relative point numbers through 15, and 16 through 29 
although the modules are not physically adjacent. In general, the 
relationship between slot number, module type, bus address, and 
relative address is as follows: 



A set of contiguous relative addresses is defined for each 
module of a given type that is installed. Each relative 
address, when qualified by type, uniquely identifies a 
digital point or channel. 

A set of slot numbers and bus addresses, possibly not 
contiguous, is occupied by all modules of a given type. Such 
addresses may be assigned solely on the basis of hardware and 
installation considerations. Increasing relative addresses 
correspond to increasing bus addresses. 



Table 18-3 is an example of the 
interrupt points, and point 
configuration. 



relationship 
numbers for 



among bus addresses, 
a sample DSSll/DRSll 



Table 18-3 
Sample DSS/DRS Configuration 



Bus Addresses 



160030-160036 
160040-160046 

170010-170016 
170020-170026 



Module Type 



DRSll 
DRSll 

DSSll 
DSSll 



Points 



0-47. 
48.-95. 

0-47. 
48.-95. 



Interrupt Point 
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All addressing is by point number. Except for the interrupts, all 
points are numbered sequentially by type (DSS or DRS) , starting with 
the first point on the lowest address assigned to a given module type. 
Interrupt points are defined by means of a 16-bit mask word. Each bit 
in the mask defines an interrupting module; high-order bits 
correspond to increasing bus addresses. 



18.2 LUN INFORMATION 

A request for logical unit information returns the following 
device-dependent data in words 2 through 5 of the buffer: 

WD 02 - 

WD 03 - Undefined 

WD 04 - Undefined 

WD 05 - 



18.3 ASSEMBLY LANGUAGE INTERFACE 

Table 18-4 summarizes standard and device-specific QIO functions 
supported by the ICS/ICR driver. Only the five functions indicated by 
a footnote are supported by the DSS/DRS driver. 



Table 18-4 
Summary of Industrial Control QIO Functions 



Format 



QIO$C lO.CCI, . . . ,<stadd,sizb,tevf> 



QIO$C lO.CTI, . . . ,<stadd ,sizb,tevf , 
arv> 

QIO$C lO.CTY, . . . ,<stadd,sizb,tevf> 



QIO$C 


lO.DCI, . . . 


QIO$C 


10. DTI,. . . 


QIO$C 


lO.DTY,. .. 


QIO$C 


lO.FLN, . .. 


QIO$C 


lO.ITI, ...,<mn,ic> 


QIO$C 


lO.LDI, . . . ,<tname. 



Function 



QIOSC 



lO.LKE, . . . ,<tname, [ ,tevf ] > 



CONNECT a buffer to 
digital interrupts 

CONNECT a buffer to 
counter interrupts 

CONNECT a buffer to 
terminal interrupts 

Disconnect a buffer from 
di ital interrupts 

Disconnect a buffer from 
counter interrupts 

Disconnect a buffer from 
terminal interrupts 

Set controller off line 

INITIALIZE a counter 

LINK task to digital 
interrupts 

LINK task to error 
interrupts 



(continued on next page) 



18-8 



INDUSTRIAL CONTROL SUBSYSTEMS 



Table 18-4 (Cont.) 
Summary of Industrial Control QIC Functions 



Format 



QIOSC IO.LTI,...,<tname, [,tevf] 
en [ ,arv] > 

QIO$C lO.LTY, . . . ,<tname, [,tevf] > 



QIO$C lO.MLO, . . . ,<opn,pp,dp>l 

QIO$C lO.MSO, . . .,<opn,dp> 

QIO$C lO.NLK, ...,<tname>l 

QIO$C lO.ONL,... 

QIOSC lO.RAD,. . , ,<stadd>l 

QIO$C lO.RBC,.. , ,<stadd,size, 
stcnta> 

QIO$C lO.SAO, . . . ,<chn,vout> 

QIO$C lO.UDI,.. .,<tname>l 

QIOSC IO.UER,..,,<tname> 

QIO$C lO.UTI, .. , ,<tname> 

QIO$C lO.UTY,.. .,<tname> 

QIOSC lO.WLB,.. . ,<stadd,sizb> 



Function 



LINK task to counter 

interrupts 

LINK task to remote 
terminal interrupts 

OPEN or close bistable 
digital output points 

PULSE momentary digital 
output points 

UNLINK a task from all 
interrupts 

Place ICS/ICR controller 
online 

READ activating data 

INITIATE multiple A/D 
conversions 

PERFORM analog output 

UNLINK a task from 
digital interrupts 

UNLINK a task from error 
interrupts 

UNLINK a task from 
counter interrupts 

UNLINK a task from 
terminal interrupts. 

TRANSMIT data to the ICR 
remote terminal 



1. These functions are supported by the DSS/DRS driver, 



arv 



chn 



en 



The starting address of a buffer containing initial or reset 
counter values. The buffer must be aligned on a word boundary. 



The D/A channel number, 



The counter number. 
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csm 

The change-of-state mask, 

dp 

The binary data pattern. 

ic 

The initial count. 

mn 

The module number. 



opn 



The first bistable (latching) digital output point number. This 
value must be on a module boundary (evenly divisible by 16). 



pn 

The point number (must be assigned on a module boundary) 

PP 

A 16-bit mask. 



sizb 

The data buffer size in bytes. For a circular buffer connected 
to unsolicited interrupts, this value must be even and large 
enough to include one entry plus the 2-word header. 



size 



The data and control buffer size in bytes. This value must be an 
even number that is greater than 0. 



stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



staddb 



The starting address of the terminal output buffer (may be 
aligned on a byte boundary). 
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stcnta 



The starting address of the control buffer (must be on a word 
boundary) ; each control buffer word must be constructed as 
described in Table 18-5 (Section 18.3.2). 



tevf 



An event flag number in the range to 96, (if the group-global 
event flag SYSGEN option was selected) , or to 64 if 
group-global event flags are not supported. 



tname 



A task name composed of 1 to 6 alphanumeric characters in a 
2-word RADIX-50 format. Two arguments, each containing three 
characters, are required for this parameter. For example, the 
task name ICNAME is specified as: 

<''RICN,''RAME, . ..> 

If the task name is less than four characters, a null argument 
must be specified as follows for task ABC: 

<''RABC,,. . .> 



vout 

A binary number between and 1023. that is to be converted to 
an analog output. 

The following sections contain a detailed description of each 
function. In the discussion of QIO request parameters, the following 
conventions apply. 

All numbering is relative. 

Module numbers start at beginning with the first module of a given 
type. Increasing module numbers correspond to increasing physical bus 
addresses. 

Channel numbers start at 0, with channel as the first channel on the 
first module of a given type. 

Point numbers start at with point as the first point on the first 
module of a given type. Points within a module are numbered "from 
right to left" in increasing order. 

It should be remembered that there is no requirement for ICS/ICR 
modules of a given type to occupy contiguous slots; thus, for 
example, digital points 15(10) and 16(10) need not reside on 
physically adjacent modules. This restriction does apply to DSS/DRS 
modules, however. 
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It is assumed that the number of points or channels per module is a 
constant for each generic type. Specifically, the following weights 
apply: 

1- Each ICS/ICR Digital I/O Module contains 16 points. 

2. Each DSS/DRS Digital I/O Module contains 48 points. 

3. Each. Counter Module contains 1 channel, 

4. Each D/A Module contains 4 channels. 

5. Each A/D Converter contains 120 channels. 

As stated above, an A/D converter is assigned a block of 120 channels. 
The number of channels in use within the block depends on the number 
of multiplexers installed. The driver will reject an attempt to 
address a nonexistent channel. 



18.3.1 General Error Status Returns 

The system recognizes and handles two kinds of status conditions when 
they occur in I/O requests: 

• Directive conditions, which indicate the acceptance or 
rejection of the QIO directive itself 

• I/O status conditions, which indicate the success or failure 
of the I/O operation 

Table 18-7 lists numerical values of returns for both assembly 
language and FORTRAN interfaces. 

The following directive and I/O status returns apply uniformly to all 
requests. 



18.3.1.1 Directive Conditions 

IS. sue - Directive accepted. The first six parameters of the QIO 

directive were valid, and sufficient dynamic memory was 

available to allocate an I/O packet. The directive is 
accepted. 

lE.ADP - Invalid address. The I/O status block or the QIO DPB was 

outside of the issuing task's address space or was not 
aligned on a word boundary. 

IE,IEF - Invalid event flag number. 

lE.ILU - Invalid logical unit number. The lun specification in a QIO 
directive was invalid for the issuing task. For example, 

there were only five logical unit numbers associated with the 
task, and the value specified for lun was greater than five. 
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IE. NOD - Insufficient dynamic memory. There was not enough dynamic 
memory to allocate an I/O packet for the I/O request. The 
user can try again later by blocking the task with a WAITFOR 
SIGNIFICANT EVENT directive. Note that WAITFOR SIGNIFICANT 
EVENT is the only effective way for the issuing task to block 
its execution, since other directives that could be used for 
this purpose themselves require dynamic memory for their 
execution (for example, MARK TIME) . 

lE.SDP - Invalid DIG number or DPB size. The directive identification 
code (DIG) or the size of the directive parameter block (DPB) 
was incorrect; the legal range for a DIG is from 1 through 
127, and all DIG values must be odd. Each individual 
directive requires a DPB of a certain size. If the size Is 
not correct for the particular directive this code is 
returned . 

lE.ULN - Unassigned LUN. The logical unit number in the QIO directive 
was not associated with a physical device unit. The user may 
recover from this error by issuing a valid Assign LUN 
directive and then reissuing the rejected directive. 



18.3.1.2 I/O Conditions 

IE. ABO - Operation aborted. The specified operation was canceled by 
lO.KIL or the request timed out while the unit was off line. 

lE.OFL - Controller off line. The physical device unit associated 
with the LUN specified in the QIO directive was not on line. 
An ICS/ICR controller may be off line because a device check 
during bootstrap load has indicated that the controller is 
not in the configuration. 

lE.DNR - Controller not ready. A nonrecoverable controller error has 
been detected. 

lE.IFC - Illegal function. A function code was included in an I/O 

request that is illegal for the ICS/ICR. The function may 

also refer to an ICS/ICR module type or function that was not 
specified during system generation. 



18.3.2 A/D Input - Read Multiple A/D Channels 

This function provides the capability of reading several A/D channels 
at any permissible gain. The driver is capable of initiating parallel 
transfers when more than one A/D converter is installed in a file box; 
however, only one interrupt module request (remote terminal or A/D) 
may be in progress at a given time. 

QIO DPB format: 

QIO$C lO.RBC, ... ,<stadd,size,stcnta> 
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stadd 



The starting address of the data buffer (must be on a word 
boundary) . 



size 



The data buffer size in bytes (must be even and greater than 0) 
the control buffer is the same size. 



stcnta 



The starting address of the control buffer (must be on a word 
boundary) ; each control buffer word must be constructed as shown 
in Table 18-5. 



Return Status: 

IS. sue - Function successfully completed. 

IE. BAD - Illegal channel or gain code specified. 

IE. BYT - Data buffer is byte aligned. Alternatively, the length 
of the buffer is not an even number of bytes. 

lE.DNR - Device not ready. A/D converter interrupt time-out 
occurred. 

Note that the second I/O status word contains a count of the 
number of conversions successfully completed. 

One control word is paired with each data word. That is, the _ data 
appearing in a data array element is obtained using the gain and 
channel number specified in the corresponding element of the control 
array. Control words specify the gain and channel in the format shown 
in Table 18-5. 

Upon receiving and validating the parameters within the I/O packet, 
the driver will initiate the following sampling procedure: 

1. The control word is fetched and tested for validity (that is, 
for legal gain and channel). If an error is encountered or 
no further control words remain, processing is terminated as 
described in Step 4. 

2. Assuming the A/D converter board is idle, the driver starts 
the conversion, sets this resource busy, and returns to step 
1. If the converter is busy, the driver returns control to 
the system after saving the data required to initiate the 
conversion when the channel becomes idle. 

3. On the occurrence of an A/D interrupt, the interrupt service 
routine initiates the appropriate processing at the non 
interrupt level that will either set the channel idle or 
initiate a previous request stored during step 2. The 
occurrence of the latter results in processing of additional 
control words as described in step 1. 
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Table 18-5 
A/D Conversion Control Word 



Bits 


Meaning 


0-11 


Channel Number range: 


0-1919 


12-15 


Gain value for 
this sample. The 
binary value is 
as follows: 

15 14 13 12 


Gain 







1 




1 


2 




10 


illegal 




11 


illegal 




10 


10 




10 1 


20 




110 


illegal 




111 


illegal 




10 


50 




10 1 


100 




10 10 


illegal 




10 11 


illegal 




110 


200 




110 1 


1000 




1110 


illegal 




1111 


illegal 



4. The converted value is returned as 12 bits, left-justified, 
in a 16-bit word, with the low-order 4 bits set to 0. 

5. A/D requests are terminated under any of the following 
conditions: 

a. All control words have been processed. 

b. A hardware error has occurred. 

c. An error in a control word has been detected. 

Regardless of the cause, the driver cannot complete request processing 
until all pending A/D transfers have gone to completion. 

Because of overlapped processing, multiple errors can occur (for 
example, a hardware error and an erroneous control word). The driver 
returns the status associated with the earliest transaction that 
caused an error condition. Thus, at the user interface, the driver 
appears to execute all conversions sequentially. 



18.3.3 Analog Output 

This function provides the capability of setting 
output channel to a specified voltage. 



a single analog 
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The driver will allow continual monitoring for digital, counter, and 
terminal inputs with the provision that, for each controller, only one 
task per module type may receive such inputs. 

Task activation is permitted for digital, terminal, and error 
interrupts. The processing related to hardware errors is discussed in 
Section 18.5. Activation of tasks by digital, counter, and terminal 
inputs is covered in Section 18.3.7. 

The driver functions described in the following paragraphs allow a 
task to continually receive interrupt data. To monitor such data, a 
task must provide: 

1. A buffer that is filled by the driver and emptied by the task 
in circular fashion 

2. An event flag that will be set upon the occurrence of each 
interrupt 

The driver will connect a single task per controller to receive 
interrupts from a specific module type. 

The buffer to be connected has the format shown below: 



FORTRAN 




Index 


Contents 


1 


driver index 


2 


user index 


3 


word of entry 


4 


word 1 of entry 



The buffer consists of a 2-word header containing the driver and user 
index, aas shown, followed by a data area that is subdivided into 
fixed-length entries. Each entry consists of a word containing the 
entry existence indicator followed by one or more words of 
device-dependent data. Such information usually consists of module 
data, relative module number, and a code identifying a module type. 
On the occurrence of an interrupt, the driver enters data in the 
location currently indicated by the driver index. This index can be 
considered as a FORTRAN index into the buffer. That is, the first 
location in the buffer is associated with the index 1. The beginning 
of the data area is associated with the first entry, index 3. Entries 
are made in a circular fashion starting at the beginning of the data 
area, filling in order of increasing memory address, and wrapping 
around to the beginning of the data area when there is insufficient 
space for an entry at the end. Note that the size of the data area 
must be an integer multiple of the entry size. 

It is expected that the connected task will maintain the user index, 
ensuring that it indicate where, in the buffer, the task is to process 
interrupt data next. 

When the task is activated by the driver, it should process data in 
the buffer starting at the location indicated by its pointer, and 
continuing in circular fashion until an existence indicator is 
encountered that is 0. 
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The existence indicator is set to +1 when a buffer entry is made. 
Except to record a hardware error, the contents of an entry are not 
altered by the driver if the indicator is nonzero. Hence, when a 
requester has removed or processed the entry, he must clear the 
existence indicator in order to free the buffer entry position. If 
the driver detects a nonzero indicator, (that is, data input has 
occurred in a burst sufficient to overrun the buffer) , the data is 
discarded and a count of data overruns is incremented. The count is 
maintained in the entry existence indicator, which, as noted above, is 
set to +1 to indicate no overruns between entries, +2 to indicate a 
hardware error entry, or a negative value recording the two's 
complement of the number of times data has been discarded between 
entries. The overrun count will never be allowed to wrap around to a 
positive value. 

In the event of a nonrecoverable controller error (remote unit 
power-fail or hard data error) all connected tasks are activated with 
the following entry in the circular buffer: 

WD 00 Hardware error indicator (+2) 



WD nn Contents of ICSR register 

WD nn+1 Physical unit number 
WD nn+2 Generic code indicator 
set to 177770(8) 



nn 

The offset to module data word. 

This entry is always placed in the buffer regardless of overflow 
status. 

The error flags are obtained from the controller ICSR word at the time 
the error was detected (see Table 18-7). 



18.3.6.1 Connect to Digital Interrupts - This function allows a 
single task to receive digital interrupt data. 

QIC DPB format: 

QIC lO.CCI, . . .,<stadd,sizb,tevf> 



stadd 



The starting address of buffer to be connected (must be word 
aligned) . 



sizb 



The length of buffer in bytes (must be even) . Minimum buffer 
length is 14 bytes. 



tevf 



The trigger event flag number, 
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Return Status: 



IS. sue - Function successfully completed. Second I/O status word 
contains the number of words passed per interrupt in the 
low byte, and the initial FORTRAN index in the high 
byte. 

IE. BYT - Buffer address is byte aligned or length is an odd 
number of bytes. 

IE. CON - Interrupt already connected to another task. 

lE.IEF - Invalid event flag number. 

lE.PRI - Task checkpointable and not fixed in memory. 

lE.SPC - Interrupt circular buffer was not wholly within the 

address space of the task. Alternatively, the buffer 

was too small for a single data entry (seven words 
minimum) . 

Entry Format: 

WD 00 - Existence Indicator 

WD Ol - Change of state indicator 

WD 02 - Module data 

WD 03 - Relative module number 

WD 04 - Generic Code 1, 2, or 3, indicating a digital interrupt 

The contents of the existence indicator have been described 
previously. 

The change-of-state indicator records those bits for which a change of 
state in the direction of interest has been detected. The direction 
of the change may be from to 1 (point closed (PCL) ) or 1 to (point 
open (POP)) depending upon the PCL or POP jumper connections on the 
digital interrupt module. The driver will assume that at least one of 
these signals is always asserted. 

The relative module number indicates the module on which the change of 
state was recognized. 

The module data word records data received at the time the interrupt 
was serviced. 

The generic code identifies the type of module that caused the 
Interrupt. A digital interrupting module may have the value 1, 2, or 
3 as selected by user-installed jumpers on the module. 



18. 3.?;. 2 Disconnect from Digital Interrupts - This function allows a 
task to terminate the processing of digital interrupt data. 

QIO DPB format: 

QIOSC lO.DCI,... 
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Return Status: 



IS. sue - Function successfully completed. Second I/O status word 
is 0. 

IE. CON - Task was not connected. Second I/O status word is 0. 



18.3.6.3 Connect to Counter Module Interrupts - This function allows 
a single task to receive counter interrupt data. 

QIO DPB format: 

QIO$C lO.CTI, . . . ,<stadd,sizb,tevf ,-arv> 

stadd 

The starting address of circular buffer (must be word aligned) . 

sizb 

The length of buffer in bytes (must be even) . Minimum buffer 
length is 12 bytes. 

tevf 

The trigger event flag number. 



arv 

The starting address of table of initial counter values (must be 
word aligned) . 

Word 03 defines an array of initial counter values. One entry is 
required for each counter installed in a physical unit. Entries are 
paired with modules in logically ascending sequence. The counter is 
set to the initial value upon receipt of the connect function and 
whenever an overflow interrupt occurs (that is, when the count reaches 
0). 

Return Status: 

IS. sue - Function successfully completed. The second I/O status 
word contains the number of words passed per interrupt 
in the low byte, and the initial FORTRAN index in the 
high byte. 

IE. BYT - Buffer address is byte aligned or length is an odd 
number of bytes. 

IE, CON - Interrupt already connected to another task. 
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lE.IEF - Invalid event flag number. 

lE.PRI - Task checkpointable and not fixed in memory. 

lE.SPC - Interrupt circular buffer or table of initial values was 

not wholly within the address space of the task. 

Alternatively, the buffer was too small for a single 
data entry (six words minimum) . 

Entry Format: 

WD 00 - Existence indicator 

WD 01 - Module data 

WD 02 - Relative module number 

WD 03 - Generic code (4, 5, or 6) 



18.3.6.4 Set Counter Initial Value - This function allows a counter 
initial value to be established. A task need not be connected to 
counter interrupts to perform this function. 

QIO DPB format: 

QIO$C lO.ITI, , . . ,<mn,ic> 



ran 



ic 



The relative module number, 



The new initial count, 



Return Status: 

IS. sue - New value submitted for output to the controller. The 
second word of I/O status is set to 0. 

IE. MOD - Nonexistent module number specified. 

Upon receipt of the request, the new initial value is immediately 
queued for output to the controller. The counter is reinitialized 
with this value on overflow if a task is connected to counter 
interrupts. 



18.3.6.5 Disconnect from Counter Interrupts - This function allows a 
task to terminate counter interrupt processing. 

QIO DPB format: 

nTn<5r m htt 
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Return Status: 

IS. sue - Function successfully completed. The second word of I/O 
status is set to 0. 

IE. CON - Task was not connected to timer interrupts. 

After disconnect is complete, counters are not reset to the initial 
value at the time of the interrupt. 



18.3.6.6 Connect to Terminal Interrupts - This function allows a task 
to receive terminal inputs from the selected ICRll controller. 

QIO DPB format: 

QIO$C lO.CTY, . ..,<stadd,sizb,tevf> 

stadd 

The address of the circular buffer (must be word aligned) . 

sizb 

The length of buffer (must be even) . The minimum buffer length 
is 12 bytes. 

tevf 

The trigger event flag number. 

Return Status: 

IS. sue - Function successfully completed. The second I/O status 
word contains the number of words passed per interrupt 
in the low byte, and the initial FORTRAN index in the 
high byte. 

IE. BYT - Buffer is byte aligned or length is an odd number of 
bytes 

IE. CON - Interrupt already connected to another task. 

lE.IEF - Invalid event flag number. 

IE. MOD - Nonexistent device. Controller is ICSll. 

lE.SPC - Interrupt circular buffer was not wholly within the 
address space of the task. Alternatively, the buffer 
was too small for a single entry (six words minimum) . 

Entry Format: 

VID 00 - Existence indicator 

WD 01 - High byte = 0, low byte = terminal input character 

WD 02 - Relative module number (normally 0) 

WD 03 - Generic code indicator (normally 0) 
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Note that words 2 and 3 are nonzero only when the entry was made as 
the result of a nonrecoverable controller error. 

All remote terminal data is conveyed to the requesting task as input, 
but with the parity bit removed. 

NOTE 

Remote terminal input is not echoed by 
the driver. 



18.3.6.7 Disconnect from Terminal Input - This function allows a task 
to discontinue the processing of terminal input. 

QIO DPB format: 

QIO$C lO.DTY,... 

Return Status: 

IS. sue - Function successfully completed. The second word of I/O 
status is set to 0. 

IE. CON - Task was not connected to remote terminal interrupts. 



18.3.7 Activating a Task by Unsolicited Interrupts 

The functions described in the following paragraphs provide the 
capability of: 

1. Activating a task in response to unsolicited interrupts 

2. Interrogating the driver to determine the reason for 
activation 

3. Removing a task from the activation list 

The QIO DPB parameters specify the task name, an optional trigger 
event flag to be set if the task is active, and device-dependent 
parameters that identify the interrupt source. A task is linked to 
interrupts (that is, made eligible for activation) provided that: 

1. The resource exists. 

2. The task is installed. 

3. No other task is linked to the resource. 

If another task is linked to the resource, the driver will reject the 
request with a status of resource-in-use (lE.RSU). A resource is 
defined as a single interrupt point, remote terminal (Control-C input 
only) , or counter module. 
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On the occurrence of the appropriate interrupt, the task is made 
active if dormant; otherwise, a trigger event flag, if specified, is 
set. The task may interrogate the driver to determine the conditions 
that caused activation, and to signify interrupt recognition. The 
function of the event flag is to allow such a task to recognize an 
event that has occurred while the task was active. Recognition is 
ensured prior to the completion of task execution by issuing the Exit 
If system directive followed by the Clear Event Flag directive. 

The linkage between a task and a specific interrupt is removed by 
issuing the appropriate unlink request with the QIC directive. 

Only one task may be associated with each interrupt source (that is, 
one task per digital interrupt point, terminal input, or counter 
module. 



NOTE 

The MCR command REMOVE automatically 
unlinks a task from all interrupts. 



18.3.7.1 Link a Task to Digital Interrupts - This function allows a 
task to be activated on the occurrence of digital interrupts. 

QIO DPB format: 

QIO$C lO.LDI, . . . ,<tname, [ ,tevf] ,pn,csm> 



tname 



A 1- to 6-character alphanumeric task name in 2-word, Radix-50 
format. 



tevf 



pn 



csm 



The trigger event flag (0 = none) . 



The point number (must be aligned on a module boundary) . 



The change-of-state mask. 

The change-of-state mask indicates those bits for which a change of 
state in the direction specified by the PCL and POP jumpers causes the 
task to be activated. Only one task may be linked to a given 
interrupt point. A change-of-state mask is not permitted. 
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Return Status: 



IS. sue - Function successfully completed. The second word of I/O 
status is set to 0. 

IE. BAD - Change-of-state mask set to 0. 

lE.IEF - Invalid event flag number. 

IE. MOD - Nonexistent module or point not aligned on a module 
boundary. 

IE. NOD - Insufficient dynamic memory to allocate secondary 
control block. 

lE.NST - Task "tname" is not installed. 

lE.RSU - One or more of the specified points is in use by other 
tasks. 



18.3.7.2 Link a Task to Counter Interrupts - This function allows a 
task to be activated by means of an interrupt from a single counter 
module. 

QIO DPB format: 

QIO$C 10. LTI, . . . ,< tname, [,tevf] ,cn[,ic]> 



tname 



A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 



tevf 

The trigger event flag (0 = none) . 

en 

The relative module number. 

ic 

The counter value (optional) . 

The counter value if nonzero, is used to reinitialize the module in a 
manner similar to that described for the Set Counter function in 
Section 18.3.6.4. Initialization may be bypassed by setting this 
parameter to 0. 

Return Status: 

IS. sue - Function successfully completed. The second word of I/O 
status is set to 0. 

lE.IEF - Invalid event flag number. 
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IE. MOD - Nonexistent module specified. 

IE. NOD - Insufficient dynamic memory to allocate a secondary 
control block. 

lE.RSU - Counter is linked to another task. 



18.3.7-3 Link a Task to Terminal Interrupts - This function allows a 
task to be activated by means of an interrupt from a remote terminal. 
The task will be activated only in response to the Control-C character 
(octal 003) . 

njQ DPB foriR9t: 

QIO$C lO.LTY, ... ,<tname, [,tevf]> 

tname 

A 1- to 6-character alphanumeric task name in 2-word, Radix-50 
format. 

tevf 

The trigger event flag (0 = none) . 

Return Status: 

IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

lE.IEF - Invalid event flag number. 

IE. MOD - Nonexistent module (unit is ICSll controller) . 

IE. NOD - insufficient dynamic storage to allocate secondary 
control block. 

lE.NST - Task "tname" is not installed. 

lE.RSU - Remote terminal is linked to another task. 



18.3.7.4 Link a Task to Error Interrupts - This function allows a 
single task to be activated whenever a remote unit power-fail or 
nonrecoverable serial line error is detected on any or all remote 
units in a system. Only one task within a system may be linked to 
error interrupts. Once linked, the selected task may receive error 
reports from any ICR controller. 

QIO DPB format: 

QIO$C IO.LKE,...,<tname, [,tevf]> 



tname 



A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 
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tevf 

The trigger event flag (0 = none) . 

Return Status: 

IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

lE.IEF - Invalid event flag number. 

IE. IPC - No ICRll subsystems are installed. 

IE. NOD - Insufficient dynamic storage to allocate secondary 
control block. 

lE.NST - Task "tname" is not installed. 

lE.RSU - Another task is linked to error interrupts. 



18.3.7.5 Read Activating Data - This function allows a task to 
determine the conditions that caused it to be activated. 

QIO DPB format: 

QIO$C lO.RAD, . . . ,<stadd> 

stadd 

The address of 6-word buffer to receive activation data (must be 
word aligned) . 

The buffer receives data in the following format: 

WD 00 - Activation indicator 

WD 01 - Physical unit number 

WD 02 - Generic code 

WD 03 - Relative module number 

WD 04 - Hardware dependent data 

WD 05 - Hardware dependent data 

The activation indicator is similar in function to the existence 
indicator used when reading circular buffer entries. The indicator is 
set to +1 on the occurrence of an interrupt to which the requesting 
task is linked, and the appropriate data is stored. The indicator is 
cleared when the data is solicited by the task. If an interrupt 
linked to the task occurs and the parameter is nonzero then the 
previously stored data is not modified and the driver sets this 
element with the two's complement of the number of linked interrupts 
not recorded. 

interrupt. 
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The generic code is identical to that specified for circular buffer 
entries, namely: 

- Terminal (Control-C) 

1,2,3 - Digital interrupt 

4,5,6 - Counter interrupt 

177770 - Fatal controller error 

Hardware-dependent data is associated with generic code and will 
consist of the following: 

Terminal : 

WD 04 - Terminal buffer contents (low byte) 

WD 05 - Undefined 
Digital Interrupts: 

WD 04 - Module data 

WD 05 - Change-of-state indicator 
Counter : 

WD 04 - Module data 

WD 05 - Undefined 
Fatal Controller Error: 

WD04 - Contents of ICSR register (see Table 18-7) 

WD05 - Contents of ICAR register (see Table 18-8) 

Return Status: 

IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

IE. BYT - Buffer address is aligned on an odd byte boundary. 

lE.NLK - Task "tname" was not linked to interrupts. 

lE.SPC - Buffer not totally within the task's address space. 

18.3.8 Unlink a Task from Interrupts 

The functions described in the following paragraphs provide the 
capability of: 

1. Unlinking a task from all interrupts on a controller 

2. Selectively unlinking a task from interrupts by module type 
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18.3.8.1 Unlink a Task from All Interrupts - This function unlinks a 
task from all interrupts on a given controller and from error 
interrupts. 

QIC DPB format: 

QIO$C lO.NLK, .. . ,<tnarae> 



tname 



A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 



Return Status: 



IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

lE.NLK - Task "tname" was not linked to interrupts. 



18.3.8.2 Unlink a Task from all Digital Interrupts - This function 
provides the capability of unlinking a task from all digital interrupt 
points on a controller. 

QIO DPB format: 

QIO$C lO.UDI, . . .,<tname> 



tname 



a 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 



Return Status: 

IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

lE.NLK - Task "tname" was not linked to the specified class of 
interrupt. 



lE.NST - Task not installed. 

IE. MOD - Nonexistent module type specified. 



18.3.8.3 Unlink a Task from Counter Interrupts - This function 
provides the capability of unlinking a task from all counter module 
interrupts. 



QIO DPB format: 

QIO$C lO.UTI, ... ,<tname> 



tname 



A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 
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Return Status: 



IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

lE.NLK - Task "tname" was not linked to the specified interrupts. 

lE.NST - Task not installed. 

IE. MOD - Nonexistent module type specified. 



18.3.8.4 Unlink a Task from Terminal Interrupts - This function 
provides the capability of unlinking a task from terminal interrupts. 

QIO DPB format: 

QIO$C lO.UTY,.. . ,<tname> 



tname 



A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 



Return Status: 



IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

lE.NLK - Task "tname" was not linked to the specified interrupts. 

lE.NST - Task not installed. 

IE. MOD - Nonexistent module specified (that is, device is an 
ICSll controller) . 



18.3.8.5 Unlink a Task from Error Interrupts - This function provides 
the capability of unlinking a task from all error interrupts. 

QIO DPB format: 

QIO$C lO.UER,. . .,<tname> 



tname 



A 1- to 6-character alphanumeric task name in 2-word Radix-50 
format. 



Return Status: 



IS. sue - Function successfully completed. The second word of I/O 
status is 0. 

lE.IFC - No ICRll controllers exist in the system. 

lE.NLK - Task "tname" was not linked to error interrupts. 

lE.NST - Task not installed. 
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18.3.9 Terminal Output 

This function allows a task to perform output to the terminal device. 
Characters are output exactly as they appear in the buffer. The 
carriage control parameter is not recognized. It should be noted that 
only one interrupt module request per controller (terminal or A/D) may 
be in progress at a given time. Thus, the driver will not initiate an 
A/D operation on a given controller, until any terminal output in 
progress for that controller has been completed. 

QIO DPB format: 

QIO$C lO.WLB, . .. ,<staddb,sizb> 

staddb 

The buffer address (may be odd) . 

sizb 

The byte count (may be odd) . 

Return Status: 

IS. sue - Function successfully completed. Second word of I/O 
status contains the number of bytes output. 

IE. MOD - Nonexistent hardware function. Request was issued for 
an ICSll controller. 



18.3.10 Maintenance Functions 

The functions described below allow a privileged task to enable and 
disable error reporting while troubleshooting or maintenance on a 
remote unit is in progress. 



18.3.10.1 Disable Hardware Error Reporting - This function allows a 
privileged task to disable error reporting and error interrupts, and 
restrict access to the controller while remote unit troubleshooting or 
module calibration is in progress (see Section 18.5.1). Upon receipt 
and validation of the request, error interrupts are disabled and 
subsequent controller time-outs are ignored. The occurrence of device 
time-out while A/D conversion or remote terminal input is in progress 
results in termination of the request with the error code IE. ABO. 
When error reporting is disabled in this manner, access to the 
controller for input or output to I/O modules is restricted to 
privileged tasks. All other requests not requiring the transmission 
of data to or from the device are permitted for all tasks. Such 
requests are as follows: 

1. Disconnect from digital, counter, or remote terminal 
interrupts 

3. Read activating data 
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4. Link to digital, remote terminal, or error interrupts 

5. Connect a buffer to digital or remote terminal interrupts 

All other requests not issued by a privileged task are rejected with 
the error code lE.DNR. 

QIC DPB format: 

QIO$C lO.FLN,... 

Return Status: 

lE.FLN - Unit already off line 
lE.PRI - Task not privileged 



18.3.10.2 Enable Hardware Error Reporting - This function allows a 
privileged task to enable error reporting and device error interrupts. 
Upon receipt and validation of the function, all device error 
interrupts are enabled and the unit is marked on line. These actions 
are performed regardless of the current state of the unit. QIO DPB 
format: 

QIO$C lO.ONL,... 

Return Status: 

IS. sue - Function successfully completed 
lE.PRI - Task not privileged 



18.3.11 Special Functions 



18.3.11.1 I/O Rundown - An I/O rundown request from the Executive 
will automatically cause the task to be disconnected from all 
interrupts. The rundown operation is not finished until any A/D input 
in progress for the task has been completed. 



18.3.11.2 Kill I/O - The kill I/O function allows a task to initiate 
I/O rundown processing for itself on any device. Request processing 
is identical to that described for I/O rundown. 

QIO DPB format: 

QIO$C lO.KIL,... 

Return Status: 

IS. sue - Function successfully completed 
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18.4 FORTRAN INTERFACE 

Table 18-6 lists the FORTRAN interface subroutines supported for the 
ICS/ICR subsystem. (D) indicates a direct access call. The six 
subroutines supported by the DSS/DRS driver are indicated by a 
footnote. 

Unless specifically noted, all subroutines are reentrant (but not 
necessarily position-independent) and may be placed in an absolute 
resident library. 



Table 18-6 
FORTRAN Interface 



Subroutine 



Function 



AIRD/AIRDW 
AISQ/AISQW 

AO/AOW 

ASICLN/ 
ASUDLN 

asislnI 

CTDI 

CTTI 

CTTY 

DFDI 

DFTI 

DFTY 

Dl/Diwl 

DOL/DOLWl 

DOM/DOMW 

lnrI 

OFLIN 
ON LIN 
RCIPT 



Input analog data from multiple channels in random 
sequence 

Read a series of sequential analog input channels 
at random gain 

Perform analog output on several channels 

Assign a LUN to an ICS/ICR controller 

Assign a LUN to a DSS/DRS controller 

Connect a circular buffer to receive digital 
interrupt data 

Connect a circular buffer to receive counter 
interrupt data 

Connect a circular buffer to receive ICRll remote 
terminal data 

Disconnect a buffer from digital interrupts 

Disconnect a buffer from counter interrupts 

Disconnect a buffer from remote terminal interrupts 

Read several 16-point digital sense fields (D) 

Latch or unlatch several 16-point bistable output 

fields 

Pulse multiple 16-point momentary digital output 
fields 

Link a task to unsolicited interrupts 

Suppress error reporting. Place unit in not ready 
status 

Status 

Read a single digital interrupt point (D) 



(continued on next page) 
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Table 18-6 (Cont.) 
FORTRAN Interface 



Subroutine 



rdactI 

RDDI 
RDTI 
RDCS 

RDWD 

RSTI 
RTO/RTOW 

unlnrI 



Function 



Read interrupt activation data 

Read the digital interrupt circular buffer 

Read the counter interrupt circular buffer 

Read digital interrupt circular buffer; return 
data on only those points for which a change of 
state has been recognized 

Read digital interrupt circular buffer; return a 
full data word 

Read a single counter module (D) 

Perforin output to a remote ICRll terminal 

Unlink a task from unsolicited interrupts 



1. These subroutines are supported by the DSS/DRS driver. 



18.4.1 Synchronous and Asynchronous Process Control I/O 

The Instrument Society of America (ISA) standard provides for 
synchronous and asynchronous I/O. Synchronous I/O is indicated by 
appending a W to the name of the subroutine (for example, AO/AOW) . 
Except for analog input and terminal output, all QIOs issued by the 
process control subroutines are serviced immediately by the driver and 
are complete upon return to the issuing task. In such cases, there is 
no functional difference between the synchronous and asynchronous 
forms; however, both forms of the name are recognized. In the case 
of A/D input and terminal output, the subroutines are functionally 
distinct. If the asynchronous form is used, execution continues and 
the calling program must periodically test the status word for 
completion. 



18.4.2 Return Status Reporting 

The I/O status parameter is a 2-word integer array. The first element 
of the array receives the status of the FORTRAN call in accordance 
with ISA convention. 

This array serves two purposes: 

1. It is the 2-word I/O status block to which the driver returns 
an I/O status code on completion of an I/O request. 

2. The first word of the status block receives a status code 
from the FORTRAN interface subroutine in ISA-compatible 
format, with the exception of the I/O pending condition, 
which is indicated by a status of 0. The ISA standard code 
for this condition is +2. 
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For asynchronous analog input and terminal output, status is set by 
means of an asynchronous trap; therefore, the trap mechanism must be 
enabled while these functions are in progress. 

For compatibility, the 2-word status block is also required for status 
returned by the direct access calls. Errors of this type that may be 
returned are: 



Word 1=3 



Word 1 = +321 



Number of points requested is 0. 
Invalid ICS/ICR module. 



The status code must be interpreted in the context of the function 
requested; however, the following general conditions will apply: 



Contents of Status Word 1 


+1 
+ 3 

3<Word K300. 

Word 1 > 300 



Meaning 

Operation pending, I/O in progress 

Successful completion 

Error in a calling argument has been 
(detected by the interface subroutine 

QIO directive rejected. Actual error 
code = -(WORD 1-3) 

Request rejected by driver. Actual 
error code = -(WORD 1 - 300) 



Table 18-7 lists all possible status values: the FORTRAN value, 
assembly language mnemonic, actual value, and related definition. 



FORTRAN 
Interface 
Value 



+0 
+ 1 
+ 3 

+4 

+8 

-6 

+ 99 

+100 



Table 18-7 
Return Status Summary 



Assembly 
Language 
Value 



+0 
+1 

none 

-1 

-5 

-6 

-96 

-97 



Assembly 
Language 
Mnemonic 



IS.PND 

IS. sue 

none 

lE.UPN 

lE.ULN 
lE.LNL 
lE.ILU 
lE.IEF 



Definition 



Operation pending 

Successful completion 

Error detected in FORTRAN 
calling sequence 

Insufficient dynamic storage 
to allocate I/O packet 

Unassigned LUN 

LUN usage interlocked 

Invalid LUN 

Invalid event flag number 



(continued on next page) 
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Table 18-7 (Cont.) 
Return Status Summary 



FORTRAN 


Assembly 


Assembly 




Interface 


Language 


Language 


Definition 


Value 


Value 


Mnemonic 




+ 101 


-98 


lE.ADP 


Part of DPB out of user's 
addressing space 


+ 102 


-99 


lE.SDP 


Invalid DIC or DPB size 


+ 301 


-1 


IE, BAD 


Bad parameters 


+ 302 


-2 


IE. IPC 


Invalid I/O function code 


+ 303 


-3 


lE.DNR 


Device not ready 


+ 306 


-6 


lE.SPC 


Illegal buffer 


+ 315 


-15 


IE. ABO 


Request aborted 


+ 316 


-16 


lE.PRI 


Privilege violation 


+ 317 


-17 


lE.RSU 


Resource in use 


+ 319 


-19 


IE. BYT 


Buffer address or length is 
odd 


+ 321 


-21 


IE. MOD 


Illegal module number 


+ 322 


-22 


IE. CON 


Another task already 
connected to interrupts 


+ 323 


-23 


IE. NOD 


Insufficient dynamic memory 
to allocate secondary control 

block 


+ 379 


-79 


lE.NLK 


Task not linked to interrupts 


+ 380 


-80 


lE.FLN 


ICRll already off line 


+ 381 


-81 


lE.NST 


Task is not installed 


+ 397 


-97 


lE.IEF 


Invalid event flag number 



18.4.3 Optional Arguments 

The calling sequences discussed in subsequent sections frequently 
contain optional arguments. These arguments are enclosed in square 
brackets within the calling sequence description. A statement 
containing such arguments may be written with these parameters deleted 
by truncating the argument list if the optional parameters are at the 
end of the calling sequence, or by replacing them with commas if they 
are embedded elsewhere in the list. Consider the routine XYZ below 
having two optional arguments: 

CALL XYZ(ibuf [,ilen] [,ival]) 

If the argument ival is to be omitted, the calling sequence would be: 

CALL XYZ(IBUF,ILEN) 
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When an optional argument in the middle of the list is to be omitted, 
it is replaced with a comma. Consider the routine XYZ , above. The 
following statement is used to omit the parameter ilen: 

CALL XYZ(IBUF, ,IVAL) 



NOTE 

In some subroutines, lun -- the logical 
unit number — is indicated to be an 
optional argument. It is optional only 
if one of the Assign LUN subroutines has 
been called (ASICLN, ASUDLN, ASISLN) . 
Otherwise, the lun argument is 



mandatory. 



18.4.4 Assigning Default Logical and Physical Units for Input and 
Output - ASICLN/ASUDLN (ICS/ICR) and ASISLN (DSS/DRS) 

The following subroutines must be called to assign and record a 
default LUN and physical unit if either parameter is to be unspecified 
in subsequent FORTRAN calls for which these parameters are optional. 

Calling Sequence: 

CALL ASICLN {[lun] [,idsw] [,iunt]) 
CALL ASUDLN ([lun] [,idsw] [,iunt]) 
CALL ASISLN(lun[,idsw] [,iunt] ) 

Before a task can issue the call to ASUDLN, the ASN command must be 
issued through MCR to assign logical device UDnn to the appropriate 
physical ICS/ICR unit. 

Argument Description: 

lun - An integer variable whose value is the number of the LUN 
to be assigned to the physical unit specified by iunt or 
unit 0. If unspecified, no LUN is assigned. The lun 
argument is mandatory for ASISLN (used for DRSll only) . 

idsw - An optional integer variable to receive the result of 
the assign lun directive. 

iunt - An optional integer variable that specifies the unit 
number to be assigned. Assumed to be if omitted. 

Return Status: 

The following values are returned to idsw: 

+1 - Assignment or function successfully completed. 

-5 - LUN usage is interlocked because LUN is assigned to a 
device that is attached to another device, or a file is 
currently open on the LUN. 

-96 - Invalid LUN. 

The call to ASUDLN assigns a LUN to logical device UD: and is 
provided for compatibility with existing UDCll software. The call to 
ASICLN assigns a LUN to device IC:. The call to ASISLN assigns a LUN 
to device IS : . 
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Upon successful issuance of the Assign LUN directive, the subroutine 
executes a Get LUN Information directive to obtain the actual unit 
numbers to be saved. It is therefore possible to alter the default 
physical unit referenced in a direct access call, by means of the ASN 
MCR function, provided that such logical assignments are done before 
the task is made active. 

Examples: 

1. Assign LUN 5 to ICR unit 3. 



10 



CALL ASICLN (5,IERR,3) 
IF(IERR) 20,10,10 



2. Assign LUN 1 to logical device UD: , unit 

a. The following MCR command is issued to create logical 
device UDO:, and assign all references to physical device 
ICl:. 

>ASN ICl: = UD: 

b. The FORTRAN call 

CALL ASUDLN (1) 

assigns logical device UDO: to LUN 1. Because of the 
previous ASN command, the Executive will assign this LUN 
to physical device ICl: and return a value of 1 for the 
unit number in response to the GET LUN Information 
directive. This value will be stored and later 
referenced whenever the physical unit number is 
unspecified in any of the FORTRAN calls that reference 
the I/O page directly. 

3. Assign LUN 6 to logical device IS:, unit 2. 

CALL ASISLN(6,,2) 

18.4.5 Analog Input 

The following routines provide the capability of performing A/D input: 

AIRD/AIRDW - ISA Standard call to read multiple channels in 

random order. This call requires one or more 

control variables containing A/D channel and gain 

in the format shown in Table 18-5 (Section 18.3.2). 

AISQ/AISQW - ISA Standard call to read multiple channels in 
sequential order. 



18.4.5.1 AIRD/AIRDW: Analog Input - Specified Channel Sequence - The 

ISA Standard call provides the capability of reading multiple A/D 
channels in a specified sequence. 



18-39 



INDUSTRIAL CONTROL SUBSYSTEMS 

Calling Sequence: 

CALL AIRD(inm,icont,idata [ , isb] ,lun) 
or 

CALL AIRDW(inm,icont, . . .etc.) 

Argument Descriptions: 

inm - Integer variable specifying the number of channels to 
be read. 

icont - An integer array of size inm containing control data in 
the format shown in Table 18-5 (Section 18.3.2). 

idat - An integer array of dimension inm to receive the 
converted values. Each element in the array is paired 
with a control element in icont that defines the 
channel and gain. 

isb - An optional 2-word integer array to receive the results 
of the call as follows: 

+1 - Conversion successfully completed. The 
second word contains the number of channels 
converted. 

+3 - Number of channels requested was 0. 

+4 - Insufficient dynamic storage to allocate 
I/O packet. 

+8 - LUN was not assigned. 

+99 - Invalid LUN. 

+301 - At least one invalid control word was 
specified. The second I/O status word 
contains the number of channels 
successfully converted. 

+303 - Device not ready. Interrupt response was 
not received from an A/D channel within one 
second after initiation. The second word 
of I/O status contains the number of 
channels successfully converted. 

+306 - Control or data buffer not wholly within 
the user's addressing space. 

+319 - Control or data buffer is byte aligned. 

lun - An integer variable specifying the ICS/ICR logical unit 
number. This parameter is required. 

Example : 

The following example illustrates how A/D throughput can be increased 
when several lAD-IA A/D Converters are in a system. This is 
accomplished by means of interleaved samples that initiate parallel 
conversions on each module. Samples are to be obtained from 12 
channels on 3 lAD-IA A/D converter modules at a gain of 1. 
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C 

C PROGRAM TO SAMPLE 12 A/D CHANNELS 

C IN RANDOM SEQUENCE FOR MAXIMUM 

C THRUPUT. 

n 

C CHANNELS TO BE SAMPLED: 

C 

C 

C 1 -A/D MODULE 

C 2 

C 3 

C 120 

C 121 -A/D MODULE 1 

C 122 

C 123 

C 240 

C 241 -A/D MODULE 2 

C 242 

C 243 

C 

C INTERLEAVED SEQUENCE FOR MAXIMUM 

C THRUPUT. 

C 

C 

C 120 

C 240 

C 1 

C 121 

C 241 

C 2 

C 122 

C 242 

C 3 

C 123 

C 243 

C 

C THE FORTRAN CONVENTION FOR ARRAY 

C STORAGE CAN BE USED TO REPRESENT 

C THE ABOVE SEQUENCE IN AN N X I INTEGER 

C CONTROL ARRAY. WHERE: 

C 

C N = NUMBER OF MODULES TO BE SAMPLED 

C I = NUMBER OF SAMPLES PER/MODULE 

C 

C ALLOCATE STORAGE FOR CONTROL ARRAY 
C 

DIMENSION ICONT (3,4) 
C 

C INITIALIZE CONTROL ARRAY FOR lAD-IA MODULE 
C 

DATA ICONT(1,1),ICONT(1,2),ICONT(1,3),ICONT{1,4)/0,1,2,3/ 

C INITIALIZE CONTROL ARRAY FOR lAD-IA MODULE 1 
C 

DATA ICONT(2,l),ICONT(2,2) , ICONT (2 , 3) , ICONT (2 , 4) /120, 121 , 122 , 123/ 

C INITIALIZE CONTROL ARRAY FOR lAD-IA MODULE 2 
C 

DATA IC0NT(3,1) ,ICONT(3,2) , ICONT ( 3 , 3) , ICONT (3 , 4) /240 , 241 , 242, 243/ 

C ALLOCATE STORAGE FOR DATA ARRAY 
C IN SIMILAR FASHION TO FACILITATE 
C CHANNEL REFERENCES 
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DIMENSION IDATA (3,4) 
C 

C BEGIN EXECUTABLE STATEMENTS 

C 



C 

C INITIATE A/D SYNCHRONOUS CONVERSION ON LUN 3 

C 

CALL AIRDW(12,IC0NT,IDATA, ,3) 



18.4.5.2 AISQ/AISQW: Analog Input - Sequential Channel Sequence - The 

ISA Standard call described below provides the capability of sampling 
multiple A/D channels in sequential order. Channels are sampled in 
increments of one, beginning with the channel specified in icont(l). 

Calling Sequence: 

CALL AISQ{inm,icont,idata [,isb],lun) 
or 

CALL AISQW(inm,icont. . .etc.) 

Argument Descriptions: 

inm - Integer variable specifying the number of elements to 
be read. 

icont - An integer array of size inm containing initial channel 
in the first element only, and gain in the format shown 
in Table 18-5 in the remaining elements. 

idat - An integer array of size inm to receive the converted 
values. Each element is paired with the corresponding 
control element in icont that defines the gain 
parameter. 

Channels are sampled sequentially starting with the 
first channel specified in element 1 of icont. 

isb - An optional 2-word integer array to receive the results 
of the call as follows: 

+1 - Conversion successfully completed. The 
second word contains the number of channels 
converted. 

+3 - Number of channels requested was 0. 

+4 - Insufficient dynamic storage to allocate 
I/O packet. 

+8 - LUN was not assigned. 

+99 - Invalid LUN. 
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+301 - At least one invalid control word was 
specified. The second I/O status word 
contains the number of channels 
successfully converted. 

+303 - Device not ready. Interrupt response was 
not received from an A/D channel within one 
second after initiation. The second word 
of I/O status contains the number of 
channels successfully converted. 

+306 - Control or data buffer is not wholly within 
the user's addressing space. 

+319 - Control or data buffer is byte aligned, 

lun - An integer variable containing the logical unit number. 
This parameter is required. 

Example: 

The following example illustrates the procedure for sequential 
sampling. Five channels are converted at gains of 1, 2, 20, 50, and 
1000, starting at channel 3. 

C 

C ALLOCATE SPACE FOR STATUS ARRAY 

C 

DIMENSION ISB (2) 
C 

C ALLOCATE SPACE FOR CONTROL ARRAY 
C AND ESTABLISH INITIAL VALUES 
C 

DIMENSION IC0NT(5) 

DATA ICONT(l) ,IC0NT(2) , ICONT (3 ) /O000003 , OOIOOOO , 0050000/ 

DATA IC0NT(4) , ICONT (5) /OlOOOOO, 0150000/ 
C 

C ALLOCATE SPACE FOR DATA ARRAY 
C 

DIMENSION IDAT (5) 



C 

C INITIATE SEQUENTIAL, ASYNCHRONOUS CONVERSION 

C VIA LUN 1 

C 

CALL AISQ(5, ICONT, IDAT, ISB, 1) 
10 IF(ISB(1) .NE.O) GO TO 20 

(continue processing) 



C 

C TEST CONVERSION STATUS 

C 

GO TO 10 
20 (test for errors or process converted data) 



END 
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18.4.6 AO/AOW: Analog Output - Multichannel 

This ISA standard routine is called to output voltage from multiple 
D/A channels. 

Calling Sequence: 

CALL AO(inm,icnt,idat [ , isb] [,lun]) 
or 

CALL AOW(inm,icnt. . .and so forth) 

Argument Descriptions: 

inm - Integer variable containing the number of channels to 
be output. 

icnt - Integer array containing the channel numbers to receive 
output. 

idat - Integer array containing the output voltage setting as 
a value between and 1023 where: 

0=0 volts dc and 

1023 = +9.99 volts (full scale). 

isb - Optional 2-word integer array to receive status. One 
of the following values is returned in isb(l). The 
second element is always 0. 

+1 - Function successfully completed. 

+3 - No channels requested. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - LUN was not assigned. 

+99 - Invalid LUN. 

+303 - Controller not ready. 

+321 - Nonexistent channel specified. 

lun - Integer variable containing the logical unit number. 

Example : 

Output the variable voltages contained in IV(1) and IV(2) to D/A 
channels 2 and 3, respectively. 
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C 

C ALLOCATE DATA ARRAY 

C 

DIMENSION IV(2) 
C 

C ALLOCATE CONTROL ARRAY 
C 

DIMENSION ICNT(2) 
C 

C ALLOCATE STATUS ARRAY 
C 

DIMENSION ISB(2) 
C 

C INITIALIZE CONTROL ARRAY 
C 

DATA ICNT (1 ) , ICNT { 2 ) /2 , 3/ 



C 

C PERFORM A/D OUTPUT VIA LUN 3 

C 

CALL AOW(2,ICNT,IV,ISB,3) 

IF (ISB(l) .GE.3) go to error processor 



18.4.7 DOL/DOLW: Digital Output - Bistable Multiple Fields 

The following ISA standard call provides the capability of latching or 
unlatching multiple 16-point bistable digital output fields. 

Calling Sequence: 

CALL DOL(inin,icnt,idat,iinsk[,isb] [,lun] ) 



or 

CALL DOLW(inm,icnt. . .and so forth) 

Argument Descriptions: 

inm - Integer variable specifying the number of fields to be 
latched or unlatched. 

icnt - Integer array containing the initial point within each 
field. 

idat - Integer array containing binary data that defines 
points within the field to be latched or unlatched. 
The state of each bit is interpreted as follows: 

1 = Latch point 

= Unlatch point 
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imsk - Integer array containing binary data that defines 
points within the field for which a change of state is 
permitted . 

A bit set to 1 defines a point that may assume the 
state defined by the corresponding bit in idat. A 
bit specifies a point for which no change of state is 
permitted . 

isb - Optional 2-word integer array to receive the results of 
the call. Status is returned in isb(l) as shown below. 
isb(2) is always 0. 

+1 - Function successfully completed. 

+3 - No points specified. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - LUN was not assigned. 

+99 - Invalid LUN. 

+303 - Controller not ready. 

+321 - Nonexistent point number specified. One or 
more points within the field do not exist. 

lun - Integer specifying the Logical Unit Number. 

Example: 

Reset points 0,1,20 and 21 

DIMENSION ICNT(2) ,IDAT(2) ,IMSK(2) 
C 

C INITIALIZE THE CONTROL ARRAY 
C 

DATA ICNT ( 1 ) , ICNT ( 2 ) /O , 20/ 
C 

C INITIALIZE MASK ARRAY TO EFFECT A 
C CHANGE-OF-STATE ONLY ON THE SPECIFIED 
C POINTS. 
C 

DATA IMSK(l) ,IMSK(2)/O000003, 0000003/ 



C 

C RESET THE SPECIFIED POINTS. ICR IS ASSIGNED 

C TO LUN 3. 

C 

CALL D0LW(2, ICNT, IDAT, IMSK, ,3) 
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18.4.8 Digital Input 

Both of the following subroutines perform their functions through 
direct access to the ICS/ICR hardware registers. Therefore, the 
physical unit number replaces LUN in the calling sequences described 
below. Note that any need for conversion of BCD encoded digital input 
into binary can be accomplished through the FORTRAN function 

IBIN=KBCD2B (IBCD) . 
Binary data can be converted to BCD through the FORTRAN function. 

IBCD=KB2BCD (IBIN) . 
The maximum input value for conversion is 9999. 



NOTE 

When the physical unit number is 
explicitly included in the calling 
sequence, it cannot be reassigned by the 
MCR command ASN. 



18.4.8.1 DI/DIW: Digital Input - Digital Sense Multiple Fields - This 
ISA standard subroutine provides the capability of reading multiple 
16-point digital sense fields. 

Calling Sequence: 

CALL DI (inra,icnt,idat[ ,isb] [,iun]) 
or 

CALL DIW( inm,icnt, . .and so forth) 

Argument Descriptions: 

inm - Integer variable specifying the number of fields to be 
read. 

icnt - Integer array containing the initial point number of 
each field. 

idat - Integer array to receive the input data. 

isb - Optional, 2-word integer array to receive the results 
of the call. The status is returned in isb (1) as 
follows: 

+1 - Function succesfully completed. 

+3 - No points requested. 

+321 - Nonexistent point requested. One or more 
points within the 16-bit field does not 
exist. 

iun - Optional integer variable specifying the physical unit 
number . 
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Example ; 



Read two contact sense fields starting at points 3 and 27 on physical 
unit IC2:. 

DIMENSION ICNT(2), IDAT (2) , ISB ( 2 ) 
DATA ICNT { 1 ) , ICNT ( 2 ) /3 , 27/ 

CALL DI (2, ICNT, IDAT, ISB, 2) 

IF (ISB(l) .GE.3) go to error procedure 



18.4.8.2 RCIPT: Digital Input - Digital Interrupt Single-Point - The 
following subroutine returns the state of a single digital interrupt 
point as a logical value. 

Calling Sequence: 

CALL RCIPT (ipt,isb[,iun] ) 

Argument Descriptions: 

ipt - Integer variable defining the point to be read. 

isb - a 2-word integer array to receive status and data as 
follows. Status is returned to isb(l). 

+1 - Function successfully completed. Data is 
returned to isb(2) as a logical value, 
where: 

."^RUE. (-1) = Point closed. 

.FALSE. (0) = Point open. 

+321 - Nonexistent point specified. 

iun - Optional integer variable defining the physical unit 
number. 

Example : 

Read the state of contact interrupt point 3 on unit 0. 
DIMENSION ISB (2) 



CALL RCIPT (3,ISB,0) 

IF (ISB(2) .EQ. .FALSE.) go to point open routine. 
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18.4.9 DOM/DOMW: Digital Output Momentary - Multiple Fields 

This ISA standard call allows multiple 16-bit fields to be pulsed. 

Calling Sequence: 

CALL DOM (inm,icnt,idat[,idx] [,isb] [,lun]) 
or 

CALL DOMW (inm,icnt. . .and so forth) 

Argument Descriptions: 

inm - Integer variable specifying the number of fields to be 
pulsed . 

icnt - Integer array containing the initial point in each 
field. 

idat - Integer array defining the points to be pulsed. A bit 
is set corresponding to each point that is to be 
triggered . 

idx - Optional dummy integer variable retained for 
compatibility with the standard form of the call. 

isb - Optional 2-word integer array to receive the results of 
the call as follows in isb(l), isb(2) is set to 0. 

+3 - Number of fields to be output is 0. 

+4 - Insufficient dynamic storage to allocate on 
I/O packet. 

+8 - LUN not assigned. 

+99 - Invalid LUN. 

+303 - Controller not ready 

+321 - Nonexistent point specified. One or more 
points within a field do not exist. 

lun - Integer variable defining the logical unit number. 

Example : 

Pulse momentary digital output fields defined by points 20, 37, and 
on LUN 1. 

DIMENSION IC0NT(3) ,IDAT(3) 

DATA ICONT(l) ,IC0NT(2) , ICONT ( 3 ) /20 , 37 , 0/ 

CALL DOM (3, ICONT, IDAT, ,1) 
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18.4,10 RTO/RTOW: Remote Terminal Output 

The following function provides the capability of transmitting a 
character string to a remote ICRll terminal. Both synchronous and 
asynchronous forms are supported. 

Calling Sequence: 

CALL RTO (ibc,ldat[,isb] [,lun] ) 
or 

CALL RTOW (ibCfidat. . . .etc.) 

Argument Descriptions: 

ibc - Integer variable specifying the number of bytes to 
output . 

idat - Byte array (LOGICAL * 1) containing the character 
string to be output. 

isb - Optional, 2-word integer array to receive the results 
of the call in isb(l) as follows. isb(2) is set to the 
number of bytes actually transferred to the device. 

- Operation pending. 

+1 - Function successfully completed. 

+3 - No bytes to be transmitted. 

+4 - Insufficient dynamic storage to allocate 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+303 - Device not ready. Terminal failed to 
respond within 1 second after character was 
transmitted . 

+306 - Part or all of buffer is out of the issuing 
task's addressing space. 

+321 - Nonexistent module. Device is ICSll. 

lun - Integer variable defining the logical unit number. 

Example : 

Output a character string to a remote terminal by the ICR unit 
assigned to LUN 3. 

CALL RTOW (32, 'APPLY +5 VOLTS TO A/D CHANNEL 10 ',,3) 
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18.4.11 Unsolicited Interrupt Data - Continual Monitoring 

Subroutines are provided that permit a FORTRAN program to continually 
monitor unsolicited interrupt data supplied to a user circular buffer, 
as described in Section 18.3.6. Such routines allow the program to 
connect a buffer for input, disconnect the buffer upon completion, and 
read and return the buffer contents in a format suitable for FORTRAN 
processing. The calls summarized below perform these functions for 
interrupting digital input modules, counters, and remote terminal 
inputs: 

Interrupting Digital Inputs 

CTDI - Connect a buffer to receive digital interrupts 

RDDI - Read the state of a single interrupting point 

RDCS - Read the state of a single interrupting point for which 
a change of state has been detected 

RDWD - Read 16 bits of interrupt data from the circular buffer 

DFDI - D-isconnect a buffer from digital interrupts 

Counter Modules 

CTTI - Connect a buffer to receive counter interrupts 

RDTI - Read the counter circular buffer 

DFTI - Disconnect a buffer from counter interrupts 

Remote Terminal Input 

CTTY - Connect a buffer to receive remote terminal inputs 
RDTY - Read remote terminal data from the circular buffer 
DFTY - Disconnect a buffer from remote terminal interrupts 



18.4.11.1 CTDI: Connect a Buffer for Receiving Digital Interrupt Data 
- The following routine allows a task to provide a circular buffer 
that will receive digital interrupt data, and to define an event flag 
that will be set upon the occurrence of each interrupt. 

Calling Sequence: 

CALL CTDI (ibuf ,lsz,iev[ ,isb] [,lun] ) 

Argument Descriptions: 

ibuf - An integer array making up the circular buffer that is 
to receive interrupt data. 

isz - Integer variable specifying the length of the circular 
buffer in words. 
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iev - Integer variable specifying the event flag that is to 
be set whenever the driver receives an interrupt from a 
digital input module. 

isb - Optional, 2-word integer array to receive the results 
of the call. The status values specified below are 
returned to isb(l). 

+1 - Function successfully completed. isb(2) 
receives the number of words passed per 
interrupt in the low byte. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+306 - Part of buffer is out of the user's address 
space or buffer is too small to accommodate 
a single entry. 

+316 - Privilege violation - task is check- 
pointable and not fixed in memory. 

+319 - Buffer address or length is an odd number 
of bytes. 

+322 - Another task is already connected to 
interrupts . 

+397 - Invalid event flag specified. 

lun - Integer variable specifying the logical unit number. 

The space allocated for the circular buffer must be large enough to 
accommodate at least one 5-word entry plus an additional 10 words of 
storage that are required by the subroutines that read circular buffer 
contents. Thus, the buffer allocation specified by the integer 
variable isz may be computed as 

isz = (10 + 5 * n) 



n 



ISZ 



The number of entries to be contained in the buffer- 



Expressed in words, 



18.4.11.2 Reading Digital Interrupt Data - Each of the following 
routines reads data that has been stored in the circular buffer and 
performs the following common processing: 

1. Detects, and optionally reports, tlie occurrence of an error 
entry that has been placed in the buffer by the driver 
because of a nonrecoverable device fault (for example, fatal 
serial line error or remote power-fail) . 
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2. Clears the trigger event flag when no further entries remain 
to be processed. 

3. Clears and optionally reports any overrun conditions. 

Only one of the following three routines can be invoked by a single 
task: 

1. RDDI: Read Digital Interrupt Data from a Circular Buffer 

The RDDI FORTRAN subroutine reads contact interrupt data from 
a circular buffer that was specified in a CTDI call (see 
18.4.11.1). It does no actual input or output, but rather 
performs a point-by-point scan of an interrupt entry in the 
buffer, returning the state of each point as a logical value. 

On the initial call to RDDI, the module number and data of 
the next interrupt entry are read from the circular buffer 
and stored for subsequent reference. The subroutine then 
sets the current data bit number n to 0, examines the state 
of data bit n, and converts bit n to a point number by the 
following formula: 

ipt = module number * 16 + n 

On each subsequent call, n is incremented by one and then 
data-bit n is examined in the stored module data. When n 
reaches 1.6, it is reset to and an attempt is made to read 
the next interrupt entry from the circular buffer. Ifa 
valid entry is not found, ipt is set negative and ict (if 
specified) is either assigned a value of or an overrun 
count that is maintained by the ICS/ICR driver. If ict is 0, 
no further entries remain. A nonzero value indicates that 
the driver received more data than could be stored in the 
buffer, and ict represents the number of entries that were 
discarded . 

The variable ict receives the control register contents that 
are set by the driver — as described in Section 
18.3.6 — whenever a nonrecoverable controller error occurs. 

Calling Sequence: 

CALL RDDI (ipt,ival[,ict] ) 

Argument Descriptions: 

ipt - A variable to which the digital input point 
number is returned. It may be set as follows: 

1. ipt if no valid entry is found 

The specific value of ipt reflects the error 
that was detected as follows: 

-1 - no data (that is, no interrupt data 
currently in buffer) 

-2 - overrun 

-3 - hardware error 

2. ipt => if the value indicated is a point 
number; the state is returned to ival. 
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ival - A variable to which the state of the point is 
returned; it may be set as follows: 

1. .FALSE. (0) if the point is open 

2. .TRUE. (-1) if the point is closed 

ict - Optional integer variable to receive the overrun 
count or the contents of the CSR register on the 
occurrence of a fatal controller error. 
Otherwise, set to 0. 



NOTE 

A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 
entries. 



2. RDCS: Read Digital Interrupt Points That Have Changed State 

The RDCS FORTRAN subroutine returns data in the format of 

subroutine RDDI — as described above — except that only 

points that have changed state are processed, resulting in 

significantly improved throughput and reduced processing 
overhead for the calling task. 

Processing specific to the routine is as follows: 

On the initial call, the module number, module data, and 
change of state information are read from the circular buffer 
and stored for later reference. The subroutine then sets the 
current data bit number n to and begins scanning the 
change-of-state word until a nonzero bit is found. The point 
number and current state are then reported as previously 
described. If no change of state is found or when no further 
bits remain to be processed, the next entry is fetched as 
described above. 

The processing of error conditions is identical to subroutine 
RDDI. 

Calling Sequence: 

CALL RDCS (ipt, ival [, ict] ) 

Argument Descriptions: 

ipt - Integer variable to receive the digital input 
point number. It may be set as follows: 

1. ipt if no valid entry is found (that is, 
overrun, error, or no data in buffer). The 
specific value of ipt reflects the error 
that was detected as follows: 

-1 - no data 
-2 - overrun 
-3 - hardware error 
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2. ipt => if the value indicated is a point 
number, the state is returned to ival. 

ival - Integer variable to receive the state of the 
point as a logical value where: 

1. .FALSE. (0) = Point open 

2. .TRUE. (-1) = Point closed 

ict - Optional integer variable. A nonzero value 
indicates that the variable has been set with an 
overrun count returned by the driver, or with 
the contents of the CSR register on the 
occurrence of a fatal controller error. 
Otherwise, set to 0. 



NOTE 

A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 
entries. 



RDWD: Read a Full Word of Digital Interrupt Data 

The following subroutine is called to return a full word of 
digital interrupt data from the circular buffer, and 
optionally change of state information. A new entry is read 
for each call; hence, throughput is high when processing is 
contingent upon several possible conditions within a module. 

Calling Sequence: 

CALL RDWD ( imod , ival [, let] [, Icos] ) 

Argument Descriptions: 

imod - Integer variable to receive the module number or 
status as follows: 

1. Imod if no data Is present or an overrun 
condition or error was detected 

The specific value of ipt reflects the error 
that was detected as follows: 

-1 - no data 
-2 - overrun 
-3 - hardware error 

2. imod => Module number. Interrupt data is 
in ival 

ival - Integer variable to receive the digital 
Interrupt data. 



18-55 



INDUSTRIAL CONTROL SUBSYSTEMS 



ict - Optional integer variable. A nonzero value 
indicates that the variable has been set with an 
overrun count returned by the driver, or with 
the contents of the CSR register on the 
occurrence of a fatal error. Otherwise, set to 
0. 

icos - Optional integer variable to receive 
change-of-state information. Bits set to a 1 
correspond to points for which a change of state 
has been recorded. 



NOTE 

A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 
entries. 



18.4.11.3 DFDI: Disconnect a Buffer from Digital Interrupts - The 
following routine is called to disconnect a task's circular buffer 
from digital interrupts. 

Calling Sequence: 

CALL DFDI ( [isb] [,lun] ) 

Argument Descriptions: 

isb - Optional 2-word integer array to receive the results of 
the call as follows. isb(2) is always 0. 

+1 - Function successfully completed 

+4 - Insufficient dynamic storage to allocate 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+322 - Task not connected to interrupts. 

lun - Integer variable containing logical unit number. 



18.4.11.4 CTTI: Connect a Buffer for Receiving Counter Data - The 
following subroutine may be called to connect a circular buffer that 
is to receive counter data, and to define an event flag that is to be 
set upon occurrence of each interrupt. 

Calling Sequence: 

CALL CTTI (ibuf ,isz,iev,iv[ ,isb] [,lun] ) 



INDUSTRIAL CONTROL SUBSYSTEMS 



Argument Descriptions: 

ibuf - An integer array making up the circular buffer that is 
to receive interrupt data. 

isz - Integer variable specifying the length of the circular 
buffer in words. 

iev - Integer variable defining an event flag that is to be 
set whenever the driver receives an interrupt from a 
counter module. 

iv - Integer array of initial counter values. One element 
is required for each counter in the physical unit. The 
value is used to initialize and reset the counter when 
a value of is reached. This parameter may be reset 
for a specific module through a call to SCTI. 

isb - Optional 2-word integer array to receive the results of 
the call. The status values specified below are 
returned to isb(l). 

+1 - Function successfully completed. isb(2) 
receives the number of words passed per 
interrupt in the low byte. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+303 - Controller not ready. 

+306 - Part of buffer is out of the user's address 
space or buffer is too small to accommodate 
a single entry^ 

+316 - Privilege violation — task is 
checkpointable and not fixed in memory. 

+319 - Buffer address or length is an odd number 
of bytes. 

+322 - Another task is already connected to 
Interrupts. 

+397 - Invalid event flag specified. 

lun - Integer variable specifying the logical unit number. 

The space allocated for the circular buffer must be large enough to 
accommodate at least one 4-word entry plus an additional 8 words of 
storage required by the subroutine that reads buffer contents (RDTI) . 
The buffer allocation specified by the variable isz may be computed as 

isz = (8 + 4 * n) 



n 

The number of entries to be contained in the buffer, 
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NOTE 

A task reading the circular buffer 
should not issue a Wait-For directive 
until a buffer-empty condition is 
reported. See Section 18.4.11.11 for an 
example of how to read circular-buffer 
entries. 



18.4.11.5 RDTI: Read Counter Data from the Circular Buffer - The 

following call returns counter interrupt data from the circular 
buffer. A new entry is read on each call. 

Calling Sequence: 

CALL RDTI (imodjival [ ,ict] ) 

Argument Descriptions: 

imod - Integer variable to receive module number and status as 
follows : 

1. imod No data in buffer, data overrun or error 
condition detected The specific value of ipt 
reflects the error that was detected as follows: 

-1 - no data 
-2 - overrun 
-3 - hardware error 

2. imod => Module number of counter. Interrupt data 
is in ival. 

ival - Integer variable to receive the counter data at 
interrupt. 

ict - Optional integer variable to receive the overrun count, 
or the ICSR contents returned by the driver on the 
occurrence of a fatal hardware error. Otherwise, set 
to 0. 



NOTE 

A task reading the circular buffer should not 
issue a Wait-For directive until a buffer-empty 
condition is reported. See Section 18.4.11.11 
for an example of how to read circular-buffer 
entries . 



18.4.11.6 Miscellaneous Counter Routines 



RSTI: Read a Counter Module 

The following routine directly accesses a counter register to 
return its current value. 
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Calling Sequence: 

CALL RSTI (iinod,isb[ ,iun] ) 

Argument Descriptions: 

imod - An integer variable containing the number of the 
counter to be read. 

isb - A 2-word integer array to receive status and 
data as follows. Status is returned to isb(l). 

+1 - Function successfully completed. 
Data is returned to isb{2). 

+321 - Nonexistent module specified. 

iun - Optional integer variable specifying the ICS/ICR 
physical unit number. 

SCTI: Reset a Counter Initial Value 

The following routine may be called by any task to revise the 
initial value that is used to activate a counter. 

Calling Sequence: 

CALL SCTI (imod, ival [, isb] [, Iun] ) 



Argument Descriptions: 

imod - Integer variable specifying the relative module 
number of the counter to be reset. 

ival - Integer value specifying the new initial value. 

isb - Optional 2-word integer array to receive status 
as follows. isb(2) is always 0. 

+1 - Function successfully completed 

+4 - Insufficient dynamic storage to 
allocate an I/O packet 

+8 - Unassigned LUN 

+99 - Invalid LUN 

+303 - Controller not ready 

+321 - Nonexistent module specified 

Iun - Integer specifying the logical unit number. 



18.4.11.7 DFTI: Disconnect a Buffer from Counter Interrupts - The 

following subroutine is called to disconnect the task's circular 
buffer from interrupts. 

Callino Sequence: 

CALL DFTI ( [isb] [,lun] ) 
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Argument Descriptions: 

Isb - Optional 2-word integer array to receive status as 
follows. isb(2) is always 0. 

+1 - Function successfully completed. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+322 - Task was not connected to interrupts. 

lun - Integer variable specifying the logical unit number. 



18.4.11,8 CTTY: Connect a Circular Buffer to Terminal Interrupts - The 
following routine allows a task to provide a circular buffer to 
receive remote terminal input data, and to define an event flag that 
is set on the occurrence of each interrupt. 

Calling Sequence: 

CALL CTTY ( ibuf , isz , iev [ , isb] [ , lun] ) 

Argument Descriptions: 

The following arguments are identical in form and function to those 
described for subroutine CTDI (see Section 18.4.11.1): 

ibuf - An integer array making up the circular buffer that 
receives interrupt data 

isz - Length of the circular buffer in words 

iev - Event flag to be set on each terminal interrupt 

Buffer size is computed as 

isz = (8 + 4 * n) 

n 

The number of entries that can be stored in the buffer. 

isb - Optional 2-word integer array to receive the results of 
the call. The status values specified below are 
returned to isb{l). 

+1 - Function successfully completed. isb(2) 
receives the number of words passed per 
interrupt in the low byte. 

I/O packet. 
+8 - Unassigned LUN. 
+99 - Invalid LUN. 



18-60 



INDUSTRIAL CONTROL SUBSYSTEMS 



+306 - Part of buffer is out of the user's address 
space or buffer is too small to accommodate 
a single entry. 

+316 - Privilege violation — task is 
checkpointable and not fixed in memory. 

+319 - Buffer address not on a word boundary or 
length is an odd number of bytes. 

+321 - Nonexistent module specified. Unit is 
ICSll. 

+322 - Another task is already connected to 
inuBrrupi-. 

+397 - Invalid event flag specified. 

lun - Logical unit number. 



18.4.11.9 RDTY: Read a Character from the Terminal Buffer - This 
subroutine retrieves a single character from the terminal circular 
buffer on each call. 

Calling Sequence: 

CALL RDTY ( ind , ichr [ , i vr] ) 

Argument Descriptions: 

ind - An integer variable to receive status as follows: 

1. =0 character retrieved from buffer is in ichr 

2. <0 no data in buffer, overrun, or hardware error 

The specific value of ind reflects the error that 
was detected as follows: 

-1 - no data 
-2 - overrun 
-3 - hardware error 

ichr - Logical * 1 or integer variable to receive the terminal 
data. If an integer is specified, only the low byte 
will be set. 

ivr - Optional integer variable to receive the overrun count, 
or the ICSR contents on the occurrence of a fatal 
hardware error. Otherwise, set to 0. 



NOTE 

A task reading the circular buffer should not 
issue a Wait-For directive until a buffer-empty 
condition is reported. See Section 18.4.11.11 
for an example of how to read circular-buffer 
entries. 
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18.4.11.10 DFTY: Disconnect a Circular Buffer from Terminal Input - 
The following routine disconnects a task's circular buffer from 
terminal inputs. 

Calling Sequence: 

CALL DFTY ( [ isb] [ , lun] ) 

Argument Descriptions: 

isb - Optional, 2-word integer array to receive status in 
isb(l) as follows. isb(2) is always set to 0. 

+1 - Function successfully completed. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+322 - Task was not connected to interrupts. 

lun - An integer specifying the logical unit number. 



18.4.11.11 Programming Example - The following are excerpts from a 
FORTRAN program that is to monitor a remote terminal for input and 
echo the received characters when a carriage return is detected. 

C 

C SPECIFY BYTE FORMAT FOR TERMINAL DATA 

C 

L0GICAL*1 TCHR 
C 

C ALLOCATE STORAGE FOR THE TERMINAL 
C BUFFER 
C 

DIMENSION IBUF(32) 
C 

C ALLOCATE STORAGE FOR THE PACKED 
C INPUT DATA SO THAT IT IS ALIGNED 
C ON A WORD BOUNDARY 
C 

DIMENSION ICHR(40) 

DIMENSION TCHR (80) 

EQUIVALENCE (TCHR,ICHR) 
C 

C ALLOCATE STORAGE FOR A 
C 2-WORD STATUS BLOCK 
C 

DIMENSION ISB(2) 
C 

C INITIALIZE ICRll LOGICAL UNIT(7) AND 
C TRIGGER EVENT FLAG NUMBER (2) 

\^ 

DATA lEV, LUN/2, 7/ 
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C 

C CONNECT THE TASK TO TERMINAL 

C INPUTS. IF CONNECT FAILS — STOP 1 

C 

CALL CTTY ( IBUF, 32 , lEV, ISB , LUN) 

IF {ISB(l) .GE.3) STOP 1 
C 

C 10— POLL THE CIRCULAR BUFFER 
C FOR DATA. ECHO THE LINE WHEN 
C 80 CHARACTERS ARE RECEIVED 
C OR A CARRIAGE RETURN IS 
C DETECTED. 
C 

10 DO 70 I = 1,80 
C 

C 20— WAIT FOR TRIGGER EVENT FLAG 

C 

20 CALL WAITER (lEV) 

C 

C 30— PACK THE CIRCULAR BUFFER DATA 

C INTO THE BYTE ARRAY 

C 

30 CALL RDTY (ISB,TCHR (I ) , IVR) 

C 

C DISPATCH ON ERROR CONDITION 
C 

GO TO (20,50,40)-ISB 

GO TO 60 
C 

C 40 — REPORT HARDWARE FAULT 
C 
40 CALL ALARM (IVR) 



GO TO 30 
C 

C 50 — REPORT OVERRUN CONDITION 

C 

50 CALL LOST (IVR) 



GO TO 30 
C 

C 60— CHECK FOR CARRIAGE RETURN, 
C EXIT TO ECHO ROUTINE IF 
C PRESENT 
C 

60 IF (TCHR(I) .EQ."15) GO TO 80 

70 CONTINUE 

C 

C 80— FALL THROUGH TO ECHO A LINE 

C 

CALL RTOW (I,TCHR, ,LUN) 
C 

C DISCONNECT TERMINAL BUFFER, EXIT 
C 

CALL DFTY (,LUN) 

CALL EXIT 

END 
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The procedure for reading the buffer in the example above may be 
summarized as follows: 

1. Wait for the trigger event flag specified in the call to 
connect the buffer. 

2. Upon regaining control, call the appropriate routine to read 
the buffer until one of the following terminal conditions is 
detected : 

a. All data has been read. 

b. An overrun count is detected. 

c. A fatal error is encountered. 



3. On the occurrence of 2a or 2b, perform any appropriate 
processing; then return to scan for additional data. 

4. If a hardware error is detected, use the ICSR register 
contents for further fault analysis and warning as 
appropriate. In the event of such an error, the event flag 
will not be set by the driver again unless normal service is 
resumed. 

5. A calling task should not execute the Wait-For directive 
until a buffer-empty condition is detected. This is because 
the user's buffer pointer is advanced after detecting and 
clearing an overrun condition, and the trigger-event flag is 
cleared only when a buffer-empty condition is detected. 



18.4.12 Unsolicited Interrupt Processing - Task Activation 

The following routines provide the capability of linking a task to an 
interrupt, soliciting information from the driver concerning how the 
task was activated, and unlinking a task from all interrupts. 



18.4.12.1 LNK: Link a Task to Interrupts - This subroutine allows 
any installed task to be activated on the occurrence of any 
unsolicited interrupt. 

Calling Sequence: 

CALL LNK (tnam,iprm[ , isb] [ ,lun] ) 
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Argument Descriptions: 

triani - Real variable containing task name in RADIX-50 
format. 

ipi^'n - A 5-word integer array containing the following 
data : 

iprra(l) - Interrupt class. May be one of the following: 

- Digital interrupts 

1 - Counters 

2 - Remote terminal (CTRL/C only) 

3 - Error interrupts 
iprm(2) - Reserved. 

iprm(3) - Optional event flag set if task to be activated is 
not dormant when the interrupt occurs. 

iprm(4) - Hardware-dependent parameters as follows: 
iprm(5) 

Interrupt Class Parameter Contents 

Diaital iprm(4) = Point number 

iprm(5) = Change-of-state mask 

Counter iprm(4) = Module number 

iprm(5) = Counter initial value 

Remote Terminal iprm(4) = not used 

iprm(5) = not used 

Error iprm(4) = not used 
iprm(5) = not used 

isb - Optional 2-word integer array to receive status in 
isb(l) as follows. isb(2) is always set to 0. 

+1 - Function successfully completed. 

+3 - Unrecognized interrupt class 
specified. 

+4 - Insufficient dynamic storage to 
allocate I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+301 - Task tnam not installed. 
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+303 - Controller not ready. 

+317 - Resource in use. Other task already 
linked to interrupt. 

+323 - Insufficient dynamic memory to 
allocate secondary control block. 

+380 - Task tnam not installed. 

+397 - Invalid event flag number specified. 

lun - Optional integer specifying the logical unit 
number . 



Example: 

Link task ALARM to report fatal hardware errors arising from a 
malfunction on any ICRll physical unit. 

DIMENSION IPRM(5) 

C 

C INITIALIZE PARAMETER ARRAY WITH: 

C 1. INTERRUPT CLASS 

C 2. RESERVED ELEMENT CLEARED 

C 3. GLOBAL EVENT FLAG 

C 

DATA IPRM(l), IPRM(2), IPRM ( 3) /3 , , 64/ 

DATA ALARM/6RALARM / 



CALL LNK (ALARM,IPRM,,7] 



18.4.12.2 RDACT: Read Activation Data - The following call allows a 
task to determine the interrupt conditions that caused it to become 
active. 

Calling Sequence: 

CALL RDACT ( iprm [ , isb] [ , lun] ) 

Argument Descriptions: 

iprni - A 6-word integer array to receive activation data 
in the following format. 

iprm(l) - Activation indicator (see Section 18.3.7.5). 

iprm (2) - Physical unit number of ICR. 
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iprm(3) - Generic code. Set to one of the following values: 

- Remote terminal 

1,2,3 - Digital interrupt 

4,5,5 - Counter interrupt 

177770 - Fatal hardware error 

iprm(4) - Relative module number. 

iprm(5) - Hardware-dependent data. 
iprm(6) 

The following data is returned based upon the type of interrupt 
module: 

Generic 
Module Type Code Parameter Contents 

Remote Terminal iprm(5) = terminal input character 

iprm(6) = undefined 

Digital Interrupt 1,2,3 iprm(5) = module data 

iprm(6) = change-of-state data 

Counter 4,5,6 iprm(5) = value of the counter at 

interrupt 
iprm(6) = undefined 

Error 177770 iprm(5) = contents of ICSR 

iprm(6) = contents of ICAR. 

isb - Optional 2-word integer array to receive status in 
isb(l) as follows. isb(2) is set to 0. 

+1 - Function successfully completed. 

+4 - Insufficient dynamic storage to allocate 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+306 - iprm array not fully within the task's 
addressing space. 

+319 - Address of iprm is odd. 

+379 - Task not linked to ICS/ICR interrupts. 

lun - Integer variable specifying the logical unit number. 
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Example : 

The following is an excerpt from a program that reads activating data 
into array TACT and conditionally exits if the event flag (lEFN) 
specified in a previous link request, issued by another task, is not 
set. 

C 

C ALLOCATE SPACE FOR DATA ARRAY 



C 



DIMENSION IACT(6) 



10 CALL RDACT (IACT,,7) 



C 

C CLOSE ALL FILES 
C 

CALL CLOSE (1) 

CALL CLOSE (2) 
C 

C EXIT IF TRIGGER EVENT FLAG IS NOT SET 
C ELSE CLEAR EVENT FLAG AND RESTART. 
C 

CALL EXITIF (lEFN) 
C 

C FLAG WAS SET. CLEAR IT AND 
C CONTINUE. 
C 

CALL CLREF (lEFN) 

GO TO 10 

STOP 

END 

The foregoing example illustrates the following considerations when a 
task is made active by ICS/ICR interrupts: 

1. To avoid race conditions, the Exit-If directive should be 
used to test the state of the event flag and conditionally 
exit. Issuing a Test Event Flag directive followed by an 
Exit would cause a flag set condition occurring after the 
test to go unrecognized. 

2. Use of the Exit-If directive bypasses the closure of all 
files that is normally done automatically by the FORTRAN 
object time system when the program executes a STOP or CALL 
EXIT statement. Thus, to exit cleanly, the program must 
explicitly close all files before invoking the directive. 



18.4.12.3 UNLNK: Remove Interrupt Linkage to a Task - The following 
call removes all linkage between a task and ICS/ICR interrupts. 
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Calling Sequence: 

CALL UNLNK ( tnam, iprm [ , isb] [ , lun] ) 

Argument Descriptions: 

tnam - Real variable containing task name in Radix-50 format. 

iprm - Integer variable containing the interrupt class. May 
be one of the following: 

- Digital Interrupts 

1 ~ Counters 

2 - Remote terminal 

3 - Error interrupts 

4 - All interrupts 

isb - Optional, 2-word integer array to receive the results 
of the call in isb(l) as follows. isb(2) is set to 0. 

+1 - Function successfully completed. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - Unassigned LUN. 

+99 - Invalid LUN. 

+379 - Task not linked to ICS/ICR interrupts. 

+380 - Task not installed. 

lun - Integer variable specifying the logical unit number. 

Example : 

Remove the linkage between task ALARM and all ICS/ICR interrupts. 

DATA ALARM/6RALARM / 

CALL UNLNK (ALARM,,,?) 

18.4.13 Maintenance Functions 

The following functions cause the ICS/ICR driver to suppress or enable 
hardware error reporting while on-line maintenance and troubleshooting 
is in progress, as described in Section 18.3.9. 

OFLIN - Place selected unit off line. 

ONLIN - Return selected unit to on-line status. 

These calls may be issued only by a privileged task. 
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18.4.13.1 OFLIN: Place Selected Unit in Offline Status - The following 
call is executed to set a controller off line: 

CALL OFLIN ([isb] [,lun]) 

Argument Descriptions: 

isb - Optional 2-word integer array to receive the results of 
the call in isb(l) as follows. isb(2) is always 0. 

+1 - Function successfully completed. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - LUN not assigned. 

+99 - Invalid LUN. 

+316 - Issuing task not privileged. 

+380 - Device already off line. 

lun - Integer variable specifying the ICS/ICR logical unit 
number. 



18.4.13.2 ONLIN: Return a Device to On-line Status - The following 
call will return the selected unit to on-line status. 

CALL ONLIN ([isb] [,lun]) 



Argument Descriptions: 

isb - Optional 2-word integer array to receive the results of 
the call in Isb(l) as follows. isb(2) is always 0. 

+1 - Function successfully completed. 

+4 - Insufficient dynamic storage to allocate an 
I/O packet. 

+8 - LUN not assigned. 

+99 - Invalid LUN. 

+316 - Issuing task not privileged. 

lun - Integer variable specifying the logical unit number. 



18.5 ERROR DETECTION AND RECOVERY 

Error Detection and recovery procedures encompass the following 
contingencies. 

i. Nonrecoverable serial line errors 

2. Power-fail at the remote station 
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3. Power recovery at the processor 

4. No response from an interrupting module 

The first two conditions are dealt with in a manner similar to that of 
other types of unsolicited interrupts. Specifically, such occurrences 
may cause a task to be activated, and are reported to all tasks that 
are connected to digital, counter, or terminal input. The following 
paragraphs discuss specific driver activity relating to each error 
condition. 



18.5.1 Serial Line Errors 

The driver detects nonrecoverable serial line errors. A 
nonrecoverable error condition is defined as the occurrence of a 
predetermined number of error interrupts in an interval of 1 second, 
or no response from the controller upon initiation of an output data 
transfer by means of the serial line. The occurrence of such a 
condition causes the driver to perform as follows: 

1. Place the controller in a "not ready" status. 

2. Disable further error interrupts. 

3. Report the condition to the task that is linked to errors, 
and to any tasks connected to receive unsolicited interrupt 
data from the faulty unit. Subsequent QIO requests that 
transfer data to or from the unit are rejected with a status 
of lE.DNR. 

Requests for interrupting modules that are pending (A/D converters and 
terminal output) are allowed to time out with the error code lE.DNR. 
The serial line error rate required to consider the link inoperative 
may be specified by the user at the time of system generation. 

After reporting the error as described above, the driver will 
automatically remove the "not ready" status when the error condition 
is not detected at the end of any 1-second interval. If requested 
during system generation, the state of the following remote modules 
will be restored as described. 

1. Bistable outputs - set to last recorded state 

2. Counters - reinitialized to last initial value 

3. Analog outputs - restored to last output value 



18.5.2 Power-Fail at a Remote Site 

The detection of AC-low from the remote site will immediately trigger 
the processing described in Section 18.5.1. The absence of AC-low 
will automatically return the unit to the "ready" status. 
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If specified, the state of the following remote modules will then be 
restored as described: 

1. Bistable outputs - set to last recorded state 

2. Counters - reinitialized to last initial value 

3. Analog outputs - restored to last output value 



18.5.3 Power Recovery at the Processor 

Power recovery by the processor will initiate the activity described 
in Section 18.5.2 for both local and remote file boxes. However, 
power recovery processing at the processor will not be reported to a 
task that is linked to error interrupts or connected to receive 
unsolicited interrupt data. 



18.5.4 Unit in Off-line Status 

A unit that is off line (see Section 18.3.9.1) is considered to be 
under manual control for purposes of diagnosis and maintenance. Under 
these conditions, error reporting as described in Section 18.5.1 is 
unnecessary and frequently undesirable, since fault indications are 
generally a by-product of these activities (that is, a remote unit is 
shut down to install an I/O module) , not the result of a genuine 
controller fault. 

Furthermore, to permit the operation of diagnostic software, it is 
advisable to attempt to service all QIO requests regardless of the 
controller status. Consequently, under these circumstances, error 
reporting and detection are modified as follows when the controller is 
off line: 

1. Access to the controller with the intention of transmitting 
data to or from the device is restricted to privileged tasks. 

2. The task linked to error interrupts and any tasks receiving 
interrupt data are not notified of remote power-fail or fatal 
serial line errors. 

3. All device error interrupts become disabled. 

4. An attempt is made to service all QIO requests if issued by a 
privileged task. If such requests time out (that is, A/D 
converter or remote terminal output) , they are terminated 
with the error code IE. ABO rather than with lE.DNR. No 
hardware errors are reported for I/O requests that are 
normally completed immediately (for example, bistable digital 
output) . 
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18.5.5 Error Data - ICSR and ICAR Registers 

Whenever a reportable error occurs, the driver returns the contents of 
the appropriate control and status register (ICSR) and, in some cases, 
the contents of the address register (ICAR), to assist in fault 
diagnosis. Tables 18-8 and 18-9 describe the contents of these 
registers . 



Table 18-8 
ICSR Contents 



Bit 


Name 


Read/ 
Write 


Description 


15 


OUTPUT BUSY 


R 


Indicates output buffer cannot 
accept new data. 


14 


MAINT 


R/W 


Maintenance. 


13 


NOT USED 


R 


Always set to 1 . 


12 


ERROR 


R 


Indicates occurrence of 
communication serial line error. 
Reset when ICAR is read. 


11 


MAINT 


R/W 


Maintenance. 


10 


PWR FAIL 


R 


Remote Power Supply AC LO indicator. 


9 


TBMT INT EN 


R/W 


Enables bit 15 of ICAR to interrupt. 


8 


MAINT 


R/W 


Maintenance. 


7 


MOD INT 


R 


Indicates I/O Module requires 
interrupt servicing. 


6 


RESET 


W 


Resets all I/O modules. Always read 
as 0. 


5 


TTY ENABLE 


R/W 


Activates TTY mode, disables I/O 
mode . 


4 


PWR FAIL INT 
ENABLE 


R/W 


Enables bit 10 to interrupt. 


3 


BMT INT ENABLE 


R/W 


Enables complement of bit 15 to 
interrupt. 


2 


MOD INT ENABLE 


R/W 


Enables Bit 7 to interrupt. 


1 


ERROR INT ENABLE 


R/W 


Enables Bit 12 to interrupt. 





RIF 


R/W 


Resets the interrupting module's 
flag when set and the module is 
addressed. This clearing action 
also resets the RIF bit. 
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Table 18-9 
ICAR Contents 



Bit 


Name 


Description 


15 
14 

13 

12 
11-08 
07-00 


TBMT 
PCL 

POP 

DA 

Generic Code 

Module Address 


Indicates TTY output buffer can 
accept new data. 

Pulse closed. This bit is set by a 
jumper on a digital interrupt 
module. This jumper is removed if 
contact closures are not of interest 
to the user. 

Pulse Opened. This bit is set by a 
jumper on a digital interrupt 
module. This jumper is removed if 
■ contacts opening are not of interest 
to the user. 

Indicates terminal character has 
been received. Cleared by reading 
terminal character. 

A 4-bit binary code that identifies 
the type of module requesting the 
interrupt. 

8-blt address of the module 
requesting the interrupt. 



18.6 DIRECT ACCESS 

Section 18,1.3 notes those ICS/ICRll functions that may be performed 
by referencing a module through its physical address in the I/O 
page. Under RSX-llM such access is accomplished by one of the 
following methods: 

1. A privileged task or any task running in an unmapped system 
has unrestricted access to the I/O page and may therefore 
access each module by absolute address. 

2. Using the Task Builder, a task may link to a global common 
area whose physical address limits span a set of locations 
in the I/O page. This method applies to either a mapped or 
unmapped system. 

The latter method allows a task to be transported to any other 
system simply by relinking. Moreover, in a mapped system the memory 
management hardware aborts all references to device registers 
outside the physical address limits of the common block. 

Because the software allows arbitrary module placement, direct 
reference, in either case, must be accomplished by translating a 
relative module number to a physical or virtual register address 
within the I/O page. This translation or mapping is performed by 
means of a table (ICTAB.MAC) that is created during system 
generation, and inserted in the system object module library. 
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The operations required to implement each method may be summarized 
as follows: 

1. Unrestricted access to the I/O page 

a. Based upon the user's response to the ICS/ICR SYSGEN 
queries, the MACRO source file ICTAB.MAC is 
automatically created under UIC [11,10] on the source 
disk. This file contains tables that describe the 
physical location of each counter, digital interrupt, 
and digital sense module in the target system. 

b. ICTAB.MAC is assembled for eventual inclusion in the 
system object module library. 

c. The MACRO source file ICOM.MAC, under UIC [11,10] on 
the source disk, is assembled to generate global 
definitions for the first ICS/ICR address on the I/O 
page and the number of ICS/ICR controllers in the 
target system. The resulting object file is 
incorporated in the system library file. 

d. A task is built containing the appropriate global 
references. Such references are resolved when the Task 
Builder automatically searches the system library. 

Steps a, b, and c are executed once. Step d is performed 
each time a task that references the ICS/ICRll is created. 



NOTE 

ICS/ICR inputs are not valid until 3ms after power 
recovery at the processor. Tasks that are 
referencing inputs directly may establish a power 
recovery AST entry point that suspends task 
execution for the necessary time interval. 



2. Access to the I/O page through a Global Common Block: 

a. Steps a and b are performed. 

b. File ICOM.MAC under UIC [11,10] is assembled to define 
the first ICS/ICR module address as a relocatable 
value, the number of I/O page locations required, and 
the number of controllers present on the target system. 

c. File ICOM.OBJ, created in step b, is linked using the 
Task Builder to create an image of the device common 
block on disk. 

d. The SET and INSTALL MCR or VMR commands are used to 
allocate space for the common block and declare the 
block resident in the target system. 

e. A task is created containing the appropriate global 
references to the common block and mapping table. 
Common block references are resolved by directing the 
Task Builder to link the task to the device common 
block (ICOM) . The mapping table reference is resolved 
from the system library module ICTAB. 
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The detailed procedure for creating the necessary object files and 
device common block is performed automatically as part of the system 
generation process, and is described fully in the RSX-llM System 
Generation and Management Guide . Therefore, the discussion in the 
following paragraphs is limited to procedures for linking to the 
device common block, and using the file ICTAB.MAC to determine 
module addresses within the I/O page. 



18.6.1 Linking a Task to the ICS/ICR Common Block 

Once the device common block has been created, a task may access 
ICS/ICR modules by linking to the common block. This can be done by 
using the Task Builder commands shown in the following example: 

TKB>TASK , LP : =TASK. OBJ 

TKB>/ 

ENTER OPTIONS: 

TKB> COMMON=ICOM:RO 

TKB>/ 

The illustration is valid for either a mapped or unmapped system. 
In both cases, the Task Builder links the task to the common block 
by relocating the global symbol definitions contained in the common 
block symbol table file ICOM.STB located under UIC [1,1]. If memory 
management is present, the Executive will map the appropriate 
physical locations into the task's virtual addressing space when the 
task is made active. 



18.6.2 Accessing the I/O Page 

After the task has been linked to the I/O page, either directly or 

through reference to the device common block, access to a specific 

ICS/ICR counter, or digital input modules during task execution, is 
a 3-step process: 

1. The task generates a request for module data by specifying 
module type, relative module number, and physical unit 
number . 

2. The data contained in module ICTAB is accessed to translate 
the arguments of step 1 to a physical offset from the 
ICS/ICR base address on the I/O page. 

3. The ICS/ICR base address, defined in the common block or 
system library module that was created from file ICOM.MAC, 
is added to the offset to compute a physical or virtual 
address and the module data is read. 

The next few paragraphs describe the format of the system library 
module ICTAB, and common block module ICOM in detail. A sample 
MACRO subroutine that references these modules is then presented. 
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18.6.2.1 Mapping Table Format - 
(file ICTAB.MAC) is used to tra 
number, and physical unit number 
digital sense modules, to the 
module on the I/O page. This mod 
in the system object module 
callable routines can be used to 
modules. The table contains o 
unit. The entry sets are arrange 
(Figure 18-1) . Entries within ea 
module type, as shown in this fig 



The mapping table created by SYSGEN 


nslate module type, relative module 


for counter, digital 


interrupt, and 


physical or virtual 


address of the 


ule must be assembled 


and inserted 


library before the st 


andard FORTRAN 


read digital input 


and counter 


ne set of entries for 


each physical 


d in order of ascendi 


ng unit number 


ch unit are arranged 


in sequence by 


ure. 







• 


DIGITAL SENSE 






DIGITAL INTERRUPT 


UNITO 
MAPPING TABLE 




COUNTER MODULES 




INCREASING 

MEMORY 

ADDRESSES 


• 
• 
• 






DIGITAL SENSE 






DIGITAL INTERRUPT 


UNIT N 
MAPPING TABLE 


\ 


COUNTER MODULES 





Figure 18-1 Mapping Table Format 

The structure of each entry is depicted in Figure 18-2. Entries are 
18 bytes long. Byte contains the highest number of modules of a 
given type that can be referenced for the controller. Bytes 2 
through 17, when indexed by relative module numbers, yield a value 
between and 255 representing the physical location of the module 
within the set of external page addresses allocated to the 
ICS/ICRll. 

The following global symbols are defined by this module: 

. ICTAB = Location of mapping tables 

I.CTBL = Length in bytes of one set of entries 



18.6.2.2 I/O Page Global Definitions - As previously mentioned, 
module ICOM contains symbolic definitions for I/O page references 
that are resolved either through unrestricted access or by means of 
a device common block that is resident on the I/O page. The 
procedures for implementing either method are carried out during 
system generation. Upon completion, the following global symbols 
are defined and later referenced by the FORTRAN callable 
subroutines : 



.ICMD = First ICS/ICR virtual or physical address 
I/O page. 

I$$C11 = Number of ICS/ICR controllers 



within the 
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If the global common block was built, the definitions above are 
contained in the symbol table file that was created by the Task 
Builder; otherwise, they are included in the system object module 
library. 1 



INCREASING 

MEMORY 

ADDRESS 



RESERVED 


MAX. MODULE NO. 


PHYSICAL MODULE NO. 


PHYSICAL MODULE NO. 


„ 


„ 


„ 


" 


„ 


„ 


., 


„ 


,, 


„ 


" 


„ 


II ir 


„ 



BYTE 

2 
4 
6 
8 

10 
12 
14 
16 



ZK-010-81 



Figure 18-2 Mapping Table Entry Format 



18.6.2.3 Sample Subroutine - The following subroutine, residing in 
the system library, utilizes the modules previously described, to 
read ICS/ICR module data. 



READ ICS/ICR-11 DIRECT ACCESS INPUTS 

LOCAL DATA 

ADDRESS OF ICS/ICR-11 MAPPING TABLES 

.ENABL LSB 
N=0 ; 

ICMAP: ; 

.REPT 12. 

.WORD .ICTAB+I.CTBL*N> 



N=N+1 



, ENDR 



1. The definitions are included in module ICOM in the system library 
or in the STB file ICOM. STB under UIC[1,1] on the system disk. The 
STB file is automatically referenced by the Task Builder in response 
to the use of the LIBR keyword. 



INDUSTRIAL CONTROL SUBSYSTEMS 



**-.RDIC-READ ICS/ICR-11 DIRECT ACCESS INPUTS 

THIS SUBROUTINE IS CALLED TO TRANSLATE RELATIVE MODULE NUMBER 
TO PHYSICAL EXTERNAL PAGE ADDRESS AND READ THE MODULE DATA. 



INPUTS: 



RO = RELATIVE MODULE NUMBER 
Rl = MODULE CODE 

WHERE: 

= CONTACT SENSE 

1 = CONTACT INTERRUPTS 

2 = COUNTERS 

STACK SETUP IS AS FOLLOWS: 

(SP)+00 = RETURN TO CALLER 
(SP)+02 = I/O STATUS BLOCK ADDRESS (NOT 
REFERENCED) . 

(SP)+04 = PHYSICAL UNIT NUMBER 
OUTPUTS: 



C/CLEAR 



C/SET: 



SPECIFIED 



RO = MODULE DATA 



NONEXISTENT PHYSICAL UNIT NUMBER OR MODULE 



,RDIC: 



MOV 


4(SP) ,R2 


CMP 


#I$$C11-1,R2 


BLO 


10$ 


ASL 


R2 


TO WORD 





MOV 



ICMAP(R2) ,R2 





ASL 


Rl 




ADD 


R1,R2 




ASL 


Rl 




ASL 


Rl 




ASL 


Rl 




ADD 


R1,R2 




TSTB 
SEC 


(R2) 




BEQ 


10$ 




INCB 


RO 




CMPB 
BLO 


(R2)+,R0 
10$ 




INC 


R2 




ADD 


R0,R2 




CLR 


RO 


EXTEND 








BISB 


(R2) ,R0 




ASL 


RO 


10$: 


MOV 
RETURN 


,ICMD(RO) ,R0 



GET PHYSICAL UNIT NUMBER 

LEGAL UNIT NUMBER? 

IF LO NO 

CONVERT PHYSICAL UNIT NUMBER 

OFFSET 

GET ADDRESS OF MAPPING TABLE 
ENTRIES FOR THIS UNIT 
CONVERT CODE TO WORD OFFSET 
MULTIPLY OFFSET BY 9 AND ADD 
TO TABLE ADDRESS 



COMPUTE OFFSET TO TABLE 

MODULE EXIST? 

ASSUME NO 

IF EQ NO 

CONVERT TO NUMBER OF MODULES 

LEGAL MODULE NUMBER? 

IF LO NO 

POINT TO TABLE ENTRIES 

OFFSET TO MODULE NUMBER 

SET FOR MOVE WITHOUT SIGN 

GET INDEX TO MODULE 
CONVERT TO WORD OFFSET 
GET MODULE DATA 



.END 
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18.7 CONVERSION OF EXISTING SOFTWARE 

The following paragraphs are intended as guidance in converting 
existing UDC or ICS software to run under the ICS/ICR-11 driver and 
associated FORTRAN support routines. The differences described here 
are restricted to module support and features that would affect 
existing software. New features, unsupported in previous systems, 
are not discussed. 



18.7.1 Features 

Principal features affecting existing software are: 

1. Support for the ICS/ICRll as a multiunit, multicontroller 
device 

2. Removal of software restrictions on the placement of 
functionally similar modules 

Multiunit support affects any software that addresses modules 
outside the range of a single file box. In general, such software 
must be modified at the source level. 

Unrestricted module placement affects MACRO-11 programs that 
directly access digital input and counter modules. Such programs 
may utilize the library routine described in Section 18.3 to read 
data from these modules. 



18.7.2 Module Support 

18.7.2.1 lAD-IA A/D Converter and IMX-IA Multiplexer 
MACRO Interface: 

Identical to UDCll driver 

FORTRAN Interface: 
Same as UDCll 

Functional Differences: 

The ICS/ICR driver can initiate parallel conversions on each 
lAD-IA in a file box that is referenced by a single QIO 
request. The UDCll driver performs all conversions serially. 

The ICS/ICR driver supports any permissible configuration of 
lAD-IA A/D converters and IMX-IA multiplexers. The UDCll 
driver requires that eight module slots be reserved for each 
lAD-IA in the system regardless of the actual number of 
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18.7.2.2 16-Bit Binary Counter 
MACRO Interface: 

Identical to UDCll driver 

FORTRAN Interface: 

Same as UDCll; however, if the counter is read through a call 
to RDTI, then the task must be relinked to incorporate the 
revised FORTRAN Interface routine. 



Trnnr'l-lf-xnal Hi ^f 



a y- or\ 



ces : 



The ICS/ICR driver permits any task to reset an initial counter 
value (with FORTRAN call SCTI or through the 10. ITI QIO 
function) . The UDCll driver restricts this operation to a task 
that has connected to counter interrupts. 



18.7.2.3 Bistable Digital Output 

MACRO Interface: 

Identical to UDCll 

FORTRAN Interface: 

Identical to UDCll 

Functional Differences: 
None 

18.7.2.4 Momentary Digital Output 

MACRO Interface: 

User interface is achieved with the QIO lO.MSO issued to the 

ICS/ICR-11 driver. The UDCll driver does not support this 

function since the module may be accessed directly through the 
UDC device common block. 



FORTRAN Interface: 

Identical to UDCll; however, existing FORTRAN tasks must be 
relinked to include ICS/ICRll FORTRAN interface routines. 

Functional Differences: 

Momentary output operations are now processed by the ICS/ICR 
driver, rather than through direct access to the I/O page. 
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18.7.2.5 Noninterrupting Digital Input 

MACRO Interface: 

MACRO Interface is by means of the ICS/ICRll device common 
block and mapping table described in Section 18.6. 

FORTRAN Interface: 

Identical to UDCll; however, existing tasks must be relinked 
to include revised ICS/ICRll FORTRAN interface routines. 

Functional Differences: 
None 



18,7.2.6 Analog Output 

MACRO Interface: 

User interface is achieved with the QIO 10. SAO issued to the 
ICS/ICR driver. The UDCll driver does not support this 
function since the module may be accessed directly through the 
UDC device common block. 

FORTRAN Interface: 

Identical to UDCll; however, existing FORTRAN tasks must be 
relinked to include ICS/ICRll FORTRAN interface subroutines. 

Functional Differences: 

Analog output operations are now processed by the ICS/ICR 
driver rather than through direct access to the I/O page. 



18.7.2.7 Interrupting Digital Input 
MACRO Interface: 

Identical to UDCll driver 

FORTRAN Interface: 

Identical to UDCll driver; however, if digital inputs are read 
through the call to RCIPT, then the task must be relinked to 
incorporate the revised ICS/ICRll FORTRAN interface routines. 

Functional Differences: 
None 



CHAPTER 19 
NULL DEVICE DRIVER 



RSX-llM provides a driver for a software construct 
device." The mnemonic for the null device 
characteristics are as follows: 



called 
is NL: 



the "null 
and its 



• A read from NL: returns an end-of-file error (IE. EOF). 

• A write to NL: immediately returns success (IS.SUC) . 

The null device functions as a "black hole" to which you can direct 
output, and from which it will never return. It is particularly 
useful when used in conjunction with an indirect command file and MCR 
ASN commands, as in the example below. 

Figure 19-1 shows the contents of a Task Builder command file called 
TESTBLD.CMD. Symbolic device names are used for the output file, map 
file, and input file. These names may be reassigned at task-build 
time. In particular, in the example below, the map file is assigned 
to the null device and thus is thrown away. 

>ASN SY:=OU: 

>ASN NL:=MP: 

>ASN DK1:=IN: 

>TKB @TESTBLD 



OU:TEST,MP:TEST=IN: [200 , 220] TEST 

/ 

ASG=TI:2 

// 



Figure 19-1 Indirect TKB Command File TESTBLD.CMD. 
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CHAPTER 20 
GRAPHICS DISPLAY DRIVER 



20.1 INTRODUCTION 

RSX-llM provides support for two graphics display peripherals: the 
VTll and the VS60. Graphics display drivers are not supported in 
RSX-llM-PLUS systems. Each consists of a CRT display, light pen, and 
display processing unit (DPU) . Either may be purchased separately or 
as part of a complete system. For example, the GT46 is a "starter 
system" consisting of a VTll and a PDP-llT/34 with 32K words of memory 
and disk storage. 



20.1.1 VTll Graphics Display Subsystem 

The VTll is a low-cost, line-drawing graphics display subsystem. It 
steals cycles asynchronously from the CPU whose UNIBUS it shares. Its 
DPU instruction set supports the following features: 

Relative and absolute vectors — solid, long dash, short dash, 
or dotted 

Point plotting 

Character generation 

Blinking display 

Eight levels of intensity 

Light-pen interaction 



20.1.2 VS60 Graphics Display Subsystem 

The VS60 supports all these features at a higher rate of performance 
than the VTll. In addition, the VS60 supports hardware subroutining , 
scaling, and windowing. A second CRT may be added to the VS60. 



20.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the GET LUN INFORMATION system 
directive (the first characteristics word) contains Os in all bits for 
graphics display devices. Words 3, 4, and 5 are undefined. 
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20,3 QIO MACRO 

Table 20-1 lists the standard and device-specific functions of the QIO 
macro that are valid for graphics display devices. 

The standard QIO functions 10. ATT and lO.DET have little use in the 
graphics display driver, because the specific functions 10. CON and 
lO.DIS are available. 



Table 20-1 
Standard and Device-Specific QIO Functions for Graphics Displays 



Format 


Function 


STANDARD FUNCTIONS 


Attach device 
Detach device 
Cancel I/O requests 

CONNECT to graphics 
device (start DPU) 

Continue (restart DPU) 

Disconnect from graphics 
device (halt DPU) 

Stop (halt DPU) 


QIO$C 10. ATT,... 
QI0$C lO.DET,... 
QIO$C lO.KIL,... 

DEVICE-SPECIFIC FUNCTIONS 


QIO$C lO.CON,. . . ,<stadd,size 

[,lpef] [,lpast]> 

QIO$C lO.CNT,... 

QIOSC lO.DIS,... 

QIO$C lO.STP,... 



stadd 



size 



Ipef 



The starting address of a display file (must be word aligned) . 
The display file must be within the lowest 28K of physical memory 
for the VTll. 



The size of the display buffer in bytes. 



The optional number of an event flag to be set upon light-pen 
hit; in the range 1-64 (10). 



Ipast 



The optional address of an asynchronous system trap (AST) entry 
point to be used upon light-pen hit. 
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20.4 STATUS RETURNS 

Table 20-2 lists error and status conditions that are returned by the 

graphics display driver in the first word of the I/O status block. 

The second I/O status word always contains 0. 



Table 20-2 
Graphics Display Status Returns 



Code 


Reason 


IS. sue 


Successful completion 




The operation specified in the QIO directive was 




completed successfully. 


IE. ABO 


Operation aborted 




The I/O operation was cancelled by lO.KIL while in 




progress or in the I/O queue. 


IE. CNR 


Connection rejected 




The graphics device specified in an 10. CON function was 




already connected to another task. 


lE.DNA 


Device not attached 




The graphics device specified in an lO.DET function was 




not attached to the issuing task. 


lE.IEF 


Illegal event flag 




An event flag number specified in an 10. CON function 




(Ipef argument) was not in the range 1-64 (decimal) . 


lE.IFC 


Illegal function code 




A function code was specified in an I/O request that is 




illegal for graphics display devices. 


lE.SPC 


Illegal address space 




The display buffer specified in an 10. CON function 




(stadd argument) was not word aligned, or (for VTll 




only) was not completely within the lowest 28K of 




memory. 



20.5 PROGRAMMING HINTS 

The graphics display driver does not determine what appears on the 
screen of the VTll or VS60. The key to what is drawn is the 
collection of DPU instructions in the display buffer. 
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Under normal circumstances, the display buffer is generated by calls 
to a set of FORTRAN graphics subroutines. These subroutines provide a 
more convenient access to the graphics features of the hardware than 
do the raw DPU instructions. The subroutines are described in the 
DECgraphic-11 FORTRAN Reference Manual , order number DEC-11-GFRMA-A-D. 

Aborting a VTll task may cause an RSX-llM system to hang up 
indefinitely, requiring a bootstrap. The VTll DPU has no Halt 
instruction, but the I/O driver must halt the DPU before it can return 
a success status in response to an lO.KIL request. (lO.KIL is 
automatically generated when a task is aborted.) This hang situation 
cannot arise with a VS60. 
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CHAPTER 21 
LABORATORY PERIPHERAL ACCELERATOR DRIVER 



21.1 INTRODUCTION 

The Laboratory Peripheral Accelerator (LPAll-K) is an intelligent, 
direct memory access (DMA) controller for DIGITAL'S laboratory data 
acquisition I/O devices. It is a fast, flexible, and easy-to-use 
microprocessor subsystem that allows analog data acquisition rates up 
to 150,000 samples per second. The LPAll-K is designed for 
applications requiring concurrent data acquisition and data reduction 
at high rates. 

The LPAll-K is supported through a device driver and a set of 
program-callable routines. The device driver supports multiple 
controllers and can be configured as resident or loadable. The 
program-callable support routines are linked with the user's task at 
task-build time. These routines are highly modular. Therefore, a 
particular task contains only that code necessary for the facilities 
actually used. 

The LPAll-K operates in two distinct modes: dedicated and 
multirequest. The subsections that follow summarize each mode. 



21.1.1 LPAll-K Dedicated Mode of Operation 

In dedicated mode, only one user (that is, one request) can be active 

at a time and only analog I/O data transfers are supported. Up to two 

analog converters can be controlled simultaneously. Sampling is 

initiated by an overflow of the real-time clock or by an externally 
supplied signal. 



21.1.2 LPAll-K Multirequest Mode of Operation 

In multirequest mode, sampling from all device types is supported. Up 
to eight users can be simultaneously active. The sampling rate for 
each user is a multiple of the common real-time clock rate. 
Independent rates can be maintained for each user. Both the sampling 
rate and the device type are specified as part of each data transfer 
request. 
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21.2 GET LUN INFORMATION MACRO 

If a Get LUN Information system directive is issued for a LUN 
associated with an LPAll-K, word 2 (the first characteristics word) 
contains all zeros, words 3 and 4 are undefined, and word 5 contains a 
16-bit buffer preset value that controls the rate of the real-time 
clock interrupts. 



21,3 THE PROGRAM INTERFACE 

A collection of program-callable subroutines provides access to the 
LPAll-K. The formats of these calls are fully documented here for 
FORTRAN programs. MACRO-11 programmers access these same subroutines 
either through the standard subroutine linkage or through the use of 
two special-purpose macros. Optionally, MACRO-11 users can control an 
LPAll-K directly through the use of device-specific QIO functions. 
Both FORTRAN and MACRO programs must contain at least one I/O Status 
Block (lOSB) for retrieval of status information. The following 
subsections, therefore, describe: 

• The FORTRAN interface 

• The MACRO-11 interface 

• The I/O status block 



NOTE 

The subroutines documented in this 
chapter represent the high-level 
interface to the LPAll-K. Using these 
subroutines requires an understanding of 
hardware capabilities, configuration 
details, and hardware status codes as 
described in the LPAll-K Laboratory 
Peripheral Accelerator User's Guide. 



21.3.1 FORTRAN Interface 

Table 21-1 lists the FORTRAN interface subroutines for accessing the 
LPAll-K. 

The calling sequences of the routines listed in Table 21-1 are 
compatible with the K-series support routines, described in Chapter 
22, except as noted. The following subsections briefly describe the 
function and format of each FORTRAN subroutine call. 
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Table 21-1 
FORTRAN Subroutines for the LPAll-K 



Subroutine 


Function 


ADSWP 


Initiate synchronous A/D sweep 




CLOCKA 


Set Clock A rate 




C LOG KB 


Control Clock B 




CVADF 


Convert A/D input to floating point 




DASWP 


Initiate synchronous D/A sweep 




DISWP 


Initiate synchronous digital input 


sweep 


DOSWP 


Initiate synchronous digital output 


sweep 


FLT16 


Convert unsigned integer to a real 


constant 


IBFSTS 


Get buffer status 




IGTBUF 


Return buffer number 




INXTBF 


Set next buffer 




IWTBUF 


Wait for buffer 




LAMSKS 


Set masks buffer 




RLSBUF 


Release data buffer 




RMVBUF 


Remove buffer from device queue 




SETADC 


Set channel information 




SETIBF 


Set array for buffered sweep 




STPSWP 


Stop sweep 




XRATE 


Compute clock rate and preset 





21.3.1.1 ADSWP: Initiate Synchronous A/D Sweep - The ADSWP routine 
initiates a synchronous A/D input sweep through an LPS-11 or an ADll-K 
(and, if present, the AMll-K) . 

If differential input is desired for the ADll-K/AMll-K, the channel 
increment must be set to 2 by calling the SETADC routine. The default 
channel increment is 1 (single-ended input) . 
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The ADSWP call is as follows: 

CALL ADSWP (ibuf ,lbuf , [nbuf] , [mode] , [idwell] , [iefn] , [Idelay] , 
[ichn] , [nchn] , [ind] ) 

ibuf 

A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (lOSB) . 



Ibuf 



nbu 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 5. In dedicated 
mode, Ibuf must be at least 257 words. 



The number of buffers to be filled. If nbuf is omitted or set 
equal to 0, indefinite sampling occurs. The STPSWP routine 
terminates indefinite sampling. 



mode 



The sampling options. The default is 0. The mode bit values 
listed below that are preceded by a plus sign (+) are independent 
and can be added or ORed together (assuming that the sampling 
options are applicable to the mode of operation). Those values 
not preceded by a plus sign are mutually exclusive and only one 
such value can be used at a time. All bit values not listed 
below are reserved. 

The following values can be specified: 

Absolute channel addressing (default) . This mode 
allows the user to directly access all 64 channels of 
an A/D converter. 

+32 Dual A/D conversion serial/parallel. This option 
applies to dedicated mode only. It is ignored in 
multirequest mode. 

+64 Multirequest mode. If this value is not specified, the 
request is for dedicated mode. If the request mode 
does not match the mode of the hardware (that is, 
different microcode in the master microprocessor) , the 
LPAll-K rejects the request with an appropriate error 
code. 

+512 External trigger (STl) . This mode is used when a 
user-supplied external sweep trigger is desired. The 
external trigger is supplied by a jumper connecting the 
ADll-K External Start input to the KWll-K Schmitt 
Trigger 1 output. This external trigger connection can 
only be used in Dedicated Mode. If mode 512 is 

n^l'vnA.n^ 4.1 ..n^v J..,nU ^.,n4- nv^^^n^ir., ^ r*'\ ^r^\r 1\ v->4-^ ^ C 

cjtr J. fcv^ i-c:u , uiicr uocl uaCDi^ muou o^c^^xj.^ a \^-LOt^rv r\ xctuc: \j i. 

-1 for proper A/D sampling. This is non-clock-driven 
sampling . 
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+1024 Time stamp with Clock B (Multirequest mode only) . 

+2048 Event marking (Multirequest mode only) . LAMSKS must be 
called to specify an event mark channel and event mark 
mask, 

+4096 Start method. If set, digital input start. If clear, 
immediate start. LAMSKS must be called to specify a 
digital start channel and digital start mask 
(multirequest mode only) . 

+8192 Dual A/D converter (dedicated mode only) , 

+16384 Data overrun NON-FATAL/FATAL. If selected, data 
overrun is considered nonfatal. The LPAll-K 
automatically defaults to fill buffer 0. (See Section 
21.4 for a discussion of buffer management.) 



idwell 



The number of clock overflows (pulses) between data sample 
sequences. As an example, if idwell is 20 and nchn is 3, the 
following occurs: after 20 pulses, one channel is sampled on 
each of the next three pulses. Then, no sampling takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different sample rates for the same hardware clock rate and 
preset. In dedicated mode, the clock hardware rate controls 
sampling and this idwell argument is ignored. 

If compatibility with K-series support routines is desired, the 

user task must first establish the clock preset by calling the 

CLOCKA routine. The default idwell value of 1 is used in the 

sweep start command. For the K-series, this procedure sets the 
rate as desired. 



NOTE 

This parameter is called iprset in the K-series support 
routines described in Chapter 22. Its function is 
different from the idwell parameter described here. 



iefn 



The event flag (1 to 28, 30 to 96), the name of a completion 
routine, or 0. If or defaulted, event flag 30 will be used for 
internal synchronization. If iefn is an event flag, the selected 
event flag is set as each buffer is filled. Note that event flag 
29 is reserved for use by the LPAll-K support routines for 
internal synchronization. If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC (or a FORTRAN 
RETURN statement) . 
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FORTRAN completion routines must not contain any of the 
following : 

• Any I/O through the FORTRAN run-time system 

• Any use of virtual arrays 

• Any use of floating-point operations 

• Any errors, since error reporting is done through the FORTRAN 
run-time system 

• Anything else that may change the FORTRAN impure area 

Any of the above may result in fatal task errors or unpredictable 
results. 

If multiple sweeps are initiated, the user should specify 
different event flags. Adherence to this limitation cannot be 
enforced by the software. 



Idelay 



The delay from the start event (DRll-K) until the first sample in 
IRATE units. This feature is supported in multirequest mode 
only. Default or indicates no delay. 



ichn 



The number of the first channel to be sampled. The default of 
applies only if ichn was not established in a prior call to the 
SETADC routine. 



nchn 



ind 



The number of channels to sample. The default is 1. nchn may be 
set up with the SETADC routine. The number of channels specified 
are sampled at a rate of 1 per clock interrupt. If nchn equals 
1, the single channel bit is set in the mode word of the start 
RDA. 



Receives a success or failure code as follows: 

1 indicates that the sweep was successfully initialized. 

indicates an illegal argument list, or SETIBF was not 
called prior to this call. 

-1 indicates a QIO directive failure. The directive error 
code is placed In lOSB(l) in IBUF. 



NOTE 

The ind parameter is not supported by the K-series 
support routines. If compatibility with K-series 
support routines is desired, this parameter must be 
ignored . 
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21.3.1.2 CLOCKA: Set Clock A Rate - The CLOCKA routine sets the rate 
for Clock A. This routine is called as follows: 

CALL CLOCKA ( i rate , iprset , [ ind] , [ lun] ) 

irate 

The clock rate. One of the following must be specified: 

-1 Direct-coupled Schmitt Trigger 1 (used only for A/D sweeps 
in Dedicated Mode +512; not supported by K-series support 
routines) 

Clock B overflow or no rate 

1 1 MHz 

2 100 KHz 

3 10 KHz 

4 1 KHz 

5 100 Hz 

5 Schmitt Trigger 1 
7 Line frequency 



iprset 



ind 



lun 



The two's complement value for clock preset. The clock rate 
divided by the negative clock preset value yields the clock 
overflow rate. For example, to obtain a clock overflow rate of 
10 Khz with a clock rate of IMhz, iprset = -100 (minus 100 
decimal) . The XRATE routine can be used to calculate a clock 
preset value. 



Receives a success or failure code as follows: 

indicates an illegal argument list or I/O error. Possible 
causes are: microcode not loaded; driver not loaded; 
device off line or not in system. 

1 indicates Clock A set to start when sweep requested. 



The logical unit number. The default is 7. 



21.3.1.3 CLOCKS: Control Clock B - The CLOCKB routine gives the user 
control over the KWll-K Clock B. 

The CLOCKB call is as follows: 

CALL CLOCKB ([ i rate] , iprset , mode ,[ ind] ,[ lun] ) 
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irate 



The clock rate. When irate is nonzero, the clock is set running 
at the selected rate after the preset value specified by iprset 
is loaded. A irate stops the clock. When irate is or 
default, the iprset and mode parameters are ignored. 

The following values are acceptable for irate: 






Stop clock B 


1 


IMHz 


2 


100 KHz 


3 


10 KHz 


4 


1 KHz 


5 


100 Hz 


f5 


Schmitt Trigger 


7 


Line frequency 



iprset 



The count by which to divide clock rate to yield overflow rate. 
Overflow events can be used to drive clock A. The preset 
parameter must be specified as or as a negative number in the 
range -1 to -255. The value in iprset can be established by use 
of the XRATE routine. 



mode 



ind 



lun 



The options. The mode bit values listed below that are preceded 
by a plus sign (+) are independent and can be added or ORed 
together. Those values not preceded by a plus sign are mutually 
exclusive and only one such value can be used at a time. All bit 
values not listed below are reserved. 

1 indicates Clock B operates in noninterrupt mode. The 
16-bit clock is not incremented or altered. This allows a 
greater than lOKHz pulse to be sent to Clock A, 

+2 indicates the feed B to A bit will be set in the Clock B 
status register. 



Receives a success or failure code as follows: 

indicates an illegal argument list or I/O error. Possible 
causes are: microcode not loaded; driver not loaded; 
device off line or not in system. 

1 indicates Clock B started. 



The logical unit number (LUN). The default LUN is 7. 



^i-» 
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21.3.1.4 CVADF: Convert A/D Input to Floating Point - The CVADF 
routine converts an A/D input value to a floating-point number. The 
routine can be invoked as a subroutine or a function as follows: 

CALL CVADF {ival,val) 

or 

val = CVADF{ival) 



ival 



val 



A value obtained from A/D input. Bits 12-15 are 0. Bits 0-11 
represent the value. 



(REAL*4) receives the converted value. The converted value is 
calculated with the following formula: 

val = (f)4*ival) /gain 



21.3.1.5 DASWP: Initiate Synchronous D/A Sweep - The DASWP routine 
initiates synchronous D/A output to an AAll-K. 

The DASWP call is as follows: 

CALL DASWP (ibuf ,lbuf , [nbuf] , [mode] , [idwell] , [iefn] ,ldelay, 
[ichn] , [nchn] , [ind] ) 



ibuf 



A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (lOSB) . 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 5. In dedicated 
mode, Ibuf must be at least 257 words. 



nbuf 



mode 



The number of buffers to be emptied. If nbuf is omitted or set 
equal to 0, indefinite sweeping occurs. The STPSWP routine 
terminates indefinite sweeping. 



The start criteria. Except where noted, the plus sign (+) 
preceding mode bit values listed below indicates that they are 
independent and can be added or ORed together. All bit values 
not listed below are reserved. 
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The following values can be specified: 

indicates immediate start. This is the default. 

+64 Multirequest mode. If this value is not specified, the 
request is for dedicated mode. If the request mode 
does not match the mode of the hardware (that is, 
different microcode in master microprocessor) , the 
LPAll-K rejects the request with an appropriate error 
code . 

+4096 Start method. If set, digital input start. If clear, 
immediate start. LAMSKS must be called to specify a 
digital start channel and a digital start mask 
(multirequest mode only) . 

+16384 Data overrun NON-FATAL/FATAL. If selected, data 
overrun is considered nonfatal. The LPAll-K 
automatically empties buffer 0. (See Section 21.4 for 
a discussion of buffer management.) 



idwell 



The number of clock overflows (pulses) between data sample 
sequences. For example, if idwell is 20 and nchn is 3, the 
following occurs: After 20 pulses, one channel is emptied on 
each of the next three pulses. Then, no emptying takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different rates for the same hardware clock rate and preset. In 
dedicated mode, the clock hardware rate controls sampling and 
idwell in the sweep start command is ignored. 

If compatibility with K-series support routines is desired, the 
user task must first establish the clock preset by calling the 
CLOCKA routine. The default value (1) for the idwell parameter 
in the sweep start command must be used. For the K-series, this 
procedure sets the rate as desired. For the LPAll-K, this 
procedure results in idwell in the sweep call defaulting to 1, 
thus yielding the same clock rate. 



NOTE 

This parameter is called iprset in the K-series support 
routines described in Chapter 22. Its function is 
different from the idwell parameter described here. 



iefn 



An event flag number (1 to 28, 30 to 96), or the name of a 
completion routine, or 0. If or default, event flag 30 is used 
for internal synchronization. If iefn is an event flag, the 
selected event flag is set as each buffer is filled. Note that 
event flag 29 is reserved for use by the LPAll-K support routines 
for internal synchronization. If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC instruction (or 
a FORTRAN RETURN statement) . 
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FORTRAN completion routines must not contain any of the 
following : 

• Any I/O through the FORTRAN run-time system 

• Any use of virtual arrays 

• Any use of floating-point operations 

• Any errors, since error reporting is done through the FORTRAN 
run-time system 

• Anything else that may change the FORTRAN impure area 
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results. 

If multiple sweeps are initiated, the user task should specify 
different event flags. This limitation cannot be enforced by the 
LPAll driver. 

Idelay 

The delay from start event (DRll-K) until the first sample in 
irate units. A minimum delay of 150 microseconds is required 
(not verified by the LPAll driver) . This feature is supported in 
multirequest mode only. 

ichn 

The first channel number. Default is channel number 0. 

nchn 

The number of channels. Default is one channel. 

ind 

Receives a success or failure code as follows: 

1 indicates that the sweep was successfully initialized. 

indicates an illegal argument list, or SETIBF was not 
called prior to this call. 

-1 indicates a QIO directive failure. The directive error 
code is placed in lOSB(l) in IBUF. 

NOTE 

The ind parameter is not supported by the K-series 
support routines. If compatibility with K-serles 
routines is desired, this parameter must be 
ignored. 



21-11 



LABORATORY PERIPHERAL ACCELERATOR DRIVER 

21.3.1,6 DISWP: Initiate Synchronous Digital Input Sweep - The DISWP 
routine initiates a synchronous digital input sweep through a DRll-K. 
It can be called in multirequest mode only. 

The DISWP call is as follows: 

CALL DISWP (ibuf ,lbuf , [nbuf] , [mode] , [idwell] , [iefn] , [Idelay] , 
[iunit] , [nchn] , [ind] ) 



ibuf 



A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (lOSB). 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 5. 



nbuf 



mode 



The number of buffers to be filled. If nbuf is or defaulted, 
indefinite sampling occurs. The STPSWP routine is used to 
terminate indefinite sampling. 



The sampling options. The default is 0. The plus signs (+) 
preceding the mode bit values listed below indicate that they are 
independent and can be added or ORed together. All bit values 
not listed below are reserved. 

The following values can be specified: 

Immediate start. This is the default mode. 

+512 External trigger. The input sampling will be triggered 
by interrupts generated by the DRll-K's external 
control lines, or its input bits if they are interrupt 
enabled . 

+1024 Time stamped sampling with Clock B. The double word 
consists of one data word followed by the value of the 
16-bit clock at the time of the sample. I0SB(2) 
contains the number of 2-word samples in the buffer. 

+2048 Event marking. LAMSKS must be called to specify an 
event mark word and an event mark mask. 

+4096 Start method. If specified, digital input start. If 
clear, immediate start. LAMSKS must be called to 
specify a digital start channel and a digital start 
mask. The digital start channel need not differ from 
the input channel (iunit). 

+16384 Data overrun NON-FATAL/FATAL. If selected, data 
overrun is considered nonfatal. The LPAll-K 
automatically fills buffer 0. (See Section 21.4 for a 
discussion of buffer management.) 
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idwell 



The number of clock overflows (pulses) between data sample 
sequences. As an example, if idwell is 20 and nchn is 3, the 
following occurs: After 20 pulses, one channel is sampled on 
each of the next three pulses. Then, no sampling takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different sample rates for the same hardware clock rate and 
preset. 

If compatibility with K-series support routines is desired, the 
user task must first establish the clock preset by calling the 
CLOCKA routine. The default value (1) for the Idwell parameter 
in the sweep start command must be used. For the K-series, this 
procedure sets the rate as desired. For the LPAll-K, this 
procedure results in idwell in the sweep call defaulting to 1, 
thus yielding the same clock rate. 



NOTE 

This parameter is called iprset in the K-series support 
routines described in Chapter 22. Its function is 
different from the idwell parameter described here. 



iefn 



An event flag number (1 to 28, 30 to 96), or the name of a 
completion routine, or 0. If default or a value of is 
specified for iefn, event flag 30 is used for internal 
synchronization. If iefn is a valid event flag, the selected 
event flag is set as each buffer is filled. Note that event flag 
29 is reserved for use by the LPAll-K support routines for 
internal synchronization. -If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC instruction (or 
a FORTRAN RETURN statement) . 

FORTRAN completion routines must not contain any of the 
following : 

• Any I/O through the FORTRAN run-time system 

• Any use of virtual arrays 

• Any use of floating-point operations 

• Any errors, since error reporting is done through the FORTRAN 
run-time system 

• Anything else that may change the FORTRAN impure area 

Any of the above may result in fatal task errors or unpredictable 
results. 

If multiple sweeps are initiated, the user task should specify 
different event flags. This limitation cannot be enforced by the 
LPAll driver. 



Idelay 



The delay from start event (DRll-K) until the 
irate units. Default or indicates no delay. 



first sample in 
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iunit 



nchn 



ind 



The DRll-K unit number. Default is unit number 0. Values 0-4 
are valid. 



The number of channels. The LPAll-K treats each' DRll-K in its 
configuration as one channel. Default is 1 channel. 



Receives a success or failure code as follows: 

1 indicates that the sweep was successfully initialized. 

indicates an illegal argument list, or SETIBF was not 
called prior to this call. 

-1 indicates a QIC directive failure. The directive error 
code is placed in lOSB(l) in IBUF. 



NOTE 

The nchn and ind parameters are not supported by 
the K-series support routines. If compatibility 
with K-series support routines is desired, these 
last two parameters must be ignored. 



21.3.1.7 DOSWP: Initiate Synchronous Digital Output Sweep - The DOSWP 
routine initiates a synchronous digital output sweep through a DRll-K. 
It can be called in multirequest mode only. 

The DOSWP call is as follows: 

CALL DOSWP (ibuf ,lbuf , [nbuf] , [mode] , [idwell] , [iefn] ,ldelay, 
[iunit] , [nchn] , [ind] ) 



ibuf 



A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (lOSB) . 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 5. 



nbuf 



The number of buffers to be emptied. If nbuf is or default, 
indefinite emptying occurs. The STPSWP routine is used to 
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mode 

The start criteria. 

The following values can be specified in the high-order byte of 
mode : 

Immediate start. This is the default mode. 

+512 External trigger. The output sampling will be 

triggered by interrupts generated by the DRll-K's 

external control lines or its input bits if they are 
Interrupt enabled. 
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immediate start. LAMSKS must be called to specify a 
digital start channel and a digital start mask. The 
digital start channel need not differ from the output 
channel ( iunit) . 

+16384 Data overrun NGN-FATAL/FATAL. If selected, data 
overrun is considered nonfatal. The LPAll-K 
automatically fills buffer 0. (See Section 21.4 for a 
discussion of buffer management.) 



idwell 



The number of clock overflows (pulses) between data sample 
sequences. For example, if idwell is 20 and nchn is 3, the 
following occurs: After 20 pulses, one channel is activated on 
each of the next three pulses. Then, no output takes place for 
the next 20 pulses. In multirequest mode, this facility permits 
different output rates for the same hardware clock rate and 
preset. 

If compatibility with K-series support routines is desired, the 
user task must first establish the clock preset by calling the 
CLOCKA routine. The default value (1) for the idwell parameter 
in the sweep start command must be used. For the K-series, this 
procedure sets the rate as desired. For the LPAll-K, this 
procedure results in idwell in the sweep call defaulting to 1, 
thus yielding the same clock rate. 



NOTE 

This parameter is called iprset in the K-series support 
routines described In Chapter 22. Its function is 
different from the idwell parameter described here. 



iefn 



An event flag number (1 to 28, 30 to 96), or the name of a 
completion routine, or 0. If default or a value of is 
specified for iefn, event flag 30 is used for internal 
synchronization. If iefn is a valid event flag, the selected 
event flag is set as each buffer is emptied. Note that event 
flag 29 is reserved for use by the LPAll-K support routines for 
internal synchronization. If iefn is greater than 96, it is 
considered to be a completion routine that will be called with a 
JSR PC. Such routines must return with an RTS PC instruction (or 
a FORTRAN RETURN statement) . 
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FORTRAN completion routines must not contain any of the 
following : 

• Any I/O through the FORTRAN run-time system 

• Any use of virtual arrays 

• Any use of floating-point operations 

• Any errors, since error reporting is done through the FORTRAN 
run-time system 

• Anything else that may change the FORTRAN impure area 

Any of the above may result in fatal task errors or unpredictable 

results. 

If multiple sweeps are initiated, the user task should specify 
different event flags. This limitation cannot be enforced by the 
LPAll driver. 



Idelay 



The delay from start event (DRll-K) until the first sample in 
irate units. A minimum delay of 150 microseconds is required 
(not verified by the LPAll driver) . 



iunit 



The DRll-K unit number. Default is unit number 0. Values 0-4 
are valid. 



nchn 



ind 



The number of channels. The LPAll-K treats each DRll-K in its 
configuration as one channel. Default is one channel. 



Receives a success or failure code as follows: 

1 indicates that the sweep was successfully initiated. 

indicates an illegal argument list, or SETIBF was not 
called prior to this call. 

-1 indicates a QIO directive failure. The directive error 
code is placed in I0SB{1) in IBUF. 



NOTE 

The nchn and ind parameters are not supported by 
the K-series support routines. If compatibility 
with K-series support routines is desired, these 
last two parameters must be ignored. 
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21.3.1.8 FLT16: Convert Unsigned Integer to a Real Constant - The 
FLT16 routine converts an unsigned 16-bit integer to a real constant 
{REAL*4). It can be invoked as a subroutine or a function as follows: 

CALL FLT16 (ival,val) 

or 

val=FLT16(ival r,van ) 

ival 

An unsigned 16-bit integer. 

val 

The converted (REAL*4) value. 



21.3.1.9 IBFSTS: Get Buffer Status - The IBFSTS routine returns 
information on buffers being used in a sweep. 

The IBFSTS call is as follows: 

CALL IBFSTS (ibuf,istat) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 



istat 



An array with as many elements as there are buffers involved in 
the sweep. The maximum is 8. IBFSTS fills each element in the 
array with the status of the corresponding buffer. The possible 
status codes are as follows: 

+2 indicates that the buffer is in the device queue. That 
is, RLSBUF has been called for this buffer. 



+1 indicates that the buffer is in the user task queue 
That is, it is full of data (for input sweeps) or i 
available to be filled (for output sweeps) . 



indicates that the status of the buffer is unknown. 
That is, it is not the current buffer nor is it in 
either the device or the user queue. 

-1 indicates that the buffer is currently in use. 



21.3.1.10 IGTBUF: Return Buffer Number - The IGTBUF routine returns 
the number of the next buffer to use. This routine should be called 
by user-task completion routines to determine which is the next buffer 
to access. It should not be used if an event flag was specified in 
the sweep-initiating call; if an event flag was specified, use the 
IWTBUF routine. 
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IGTBUF can be invoked as a subroutine or a function as follows: 

CALL IGTBUF ( ibuf , ibuf no) 
or 

ibufno=IGTBUF(ibuf [ , ibuf no] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 

ibufno 

Receives the number of the next buffer to access. If there is no 
buffer in the queue, ibufno contains -1. 

On the return from a call to IGTBUF, the following are the possible 
combinations of ibufno and lOSB contents: 

Explanation 

Normal buffer complete. 

Buffer complete. Sweep 
terminated. There may be 
additional buffers in the 
queue filled and ready for 
processing. 

-10 No buffers in queue. 

Request still active. 

-11 No buffers in queue. Sweep 

terminated . 

-1 RSX-llM LPAll-K No buffers in queue, 
error code(lO) error code{8) Sweep terminated due to 

error condition. (Refer to 
Section 21.3.3 for error 
code summary.) Note that 
the error is not returned 
until there are no more 
buffers in the user queue. 



21.3.1.11 INXTBF: Set Next Buffer - The INXTBF routine alters the 
normal buffer selection algorithm. It allows the user task to specify 
the number of the next buffer to be filled or emptied. 

INXTBF can be invoked as a subroutine or a function as follows: 

CALL INXTBF ( ibuf , ibuf no [, ind] ) 

or 



ibufno 


lOSB(l) 


I0SB(2) 


n 


400(8) 


(Word count) 


n 


1 


(Word count) 
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ibuf 

The 40-word array specified in the call that initiated a sweep. 

ibufno 

The number of the next buffer the user wants filled or emptied. 
The buffer must already be in the device queue. 

ind 

Receives an indication of the result of the operation: 

indicates that the specified buffer was not in the device 
queue. 

1 indicates that the next buffer was successfully set. 

21.3.1.12 IWTBUF: Wait for Buffer - The IWTBUF routine allows a user 
task to wait for the next buffer to fill or empty. It should be used 
in conjunction with the specification of an event flag in the 
sweep-initiating call. This routine should not be used if a 
completion routine was specified in the call to initiate a sweep; 
when event flags are specified, use the IGTBUF routine. 

IWTBUF can be invoked as a subroutine or a function as follows: 

CALL IWTBUF ( ibuf ,[ iefn] , ibuf no) 
or 

ibufno=IWTBUF(ibuf , [iefn] , [ibufno] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 

iefn 

The event flag on which the task will wait. This should be the 
same event flag as that specified in the sweep-initiating call. 
If iefn equals or default, event flag 30 is used. 



ibufno 



Receives the number of the next buffer to be filled or emptied by 
the user task. 
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On the return from a call to IWTBUF, the following are the possible 
combinations of ibufno and lOSB contents: 

ibufno lOSB(l) I0SB(2) Explanation 

n 400(8) (word count) Normal buffer complete. 

n 1 (word count) Buffer complete. Sweep 

terminated. There may be 
additional buffers in the 
queue filled and ready for 
processing . 

-1 1 No buffers in queue. 

Sweep terminated. 

-1 RSX-llM LPAll-K No buffers in queue, 
error code(lO) error code(8) Sweep terminated due to 

error condition. (Refer 
to Section 21.3.3 for 
error code summary.) Note 
that the error is not 
returned until there are 
no more buffers in the 
user queue. 



21.3.1.13 LAMSKS: Set Masks Buffer - The LAMSKS routine initializes a 
user buffer containing a LUN, a digital start mask and event mark 
mask, and channel numbers for the two masks. The routine then assigns 
the LUN. Each DRll-K is considered to be one channel. Each channel 
has both input and output capabilities. 

LAMSKS must be called if digital input starting or event marking is to 
be utilized, or if a LUN other than the default LUN 7 will be assigned 
to LAO. LAMSKS must also be called if multiple LPAll-Ks are being 
used. If LAMSKS is to be called, it must be called prior to calling 
SETIBF. Unlike SETIBF, LAMSKS does not have to be called before each 
sweep initiation unless one or more parameters are to be changed. 

The LAMSKS call is as follows: 

CALL LAMSKS (lamskb , [ lun] , [ luni t] , [ idsc] , [ iemc] , [ idsw] , 
[lemw] , [ ind] ) 

lamskb 

A 4-word array. 

lun 

A logical unit number. Default LUN is 7. 
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iunit 

The physical unit number of the LPAll-K. Default physical unit 
number is LAO. 



idsc 

The digital start word channel. Default is channel 0, 

iemc 

The event mark word channel. Default is channel 0. 



idsw 



The digital start word mask. Default is (disable digital input 
starting) . 



lemw 

The event mark word mask. Default is (disable event marking) . 

ind 

Receives a success or failure code as follows: 

1 indicates successful initialization. 

indicates an illegal argument list. 

-n indicates a LUN assignment failure. n is the directive 
error code. 

NOTE 

If compatibility with K-series support routines is 
desired, ignore this parameter. 

For a discussion of event marking and digital starting, see the 
LPAll-K Laboratory Peripheral Accelerator User' s Guide . 



21.3.1.14 RLSBUF: Release Data Buffer - The RLSBUF routine declares 
one or more buffers free for use by the interrupt service routine. 

The RLSBUF routine must be called to release buffer (s) to the device 
queue before the sweep is initiated. The device queue must always 
contain at least one buffer to maintain continuous sampling. 
Otherwise, buffer overrun occurs (see Section 21.4 for a discussion of 
buffer management). Note that RLSBUF does not verify whether the 
specified buffers are already in a queue. 
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The RLSBUF call is as follows: 

CALL RLSBUF ( ibuf , [ ind] ,nO [ ,nl . . . ,n7 ] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 

ind 

Receives a success or failure code as follows: 

indicates illegal buffer number specified, illegal number 
of buffers specified, or a double buffer overrun has been 
detected . 

1 indicates buffer(s) successfully released. 

nO,nl,etc. 

The numbers (0-7) of the buffers to be released. A maximum of 
eight can be specified. 

21.3.1.15 RMVBUF: Remove Buffer from Device Queue - The RMVBUF rou- 
tine removes a buffer from the device queue. 

The RMVBUF call is as follows: 

CALL RMVBUF ( ibuf ,n [ , ind] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 

n 

The number of the buffer to remove. 
ind 

Receives a success or failure code as follows: 

indicates that the specified buffer was not in the device 
queue. 

1 indicates that the specified buffer was removed from the 
queue. 



21.3.1.16 SETADCs Set Channel Information - The SETADC routine 
establishes channel start and increment information for all sweeps. 
The SETIBF routine must be called to initialise the 40— word arra^' 
(ibuf) before SETADC is called. 
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If, in the call to SETADC, nchn is 1 or inc is 0, the single channel 
bit will be set in the mode word of the start RDA when the sweep start 
routine is called. 

SETADC can be invoked as a subroutine or a function as follows: 
CALL SETADC ( ibuf ,[ i flag] ,[ ichn] , [nchn] ,[ inc] ,[ ind] ) 

or 

ind = ISTADC(ibuf, [iflag] , [ichn] , [nchn] , [inc] , [ind] ) 

ibuf 

A 40-word array initialized by the SETIBF routine. 



iflag 



Ignored. It is included for compatibility with K-series support 
routines . 



ichn 



The first channel number. Default is 0. If inc equals (or 
default) , ichn is the address of a random channel list. A random 
channel list is an array of n elements, where each element is a 
channel number. The final element must have bit 15 set to 
indicate the end of the list. 



nchn 



mc 



ind 



The number of samples to be taken per sequence. Default is one 
sample. 



The channel increment. Default is 1. The user should specify an 
increment of 2 for differential A/D input. If inc equals 0, ichn 
is an array of random channels to receive input. 



Receives a success or failure code as follows: 

indicates an illegal channel number or SETIBF was not 
called prior to the SETADC call. 

1 indicates successful recording of channel information for 
the sweep call. 



21.3.1.17 SETIBF: Set Array for Buffered Sweep - The SETIBF routine 
initializes an array required by buffered sweep routines. The SETIBF 
routine must be called before every call to a buffered sweep routine. 
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The SETIBF call is as follows: 

CALL SETIBF ( ibuf , [ ind] , [lamskb] ,buf [ ,buf 1 . . .buf 7] ) 

ibuf 

A 40-word array. 

ind 

Receives a success or failure code as follows: 

indicates a parameter or buffer error. 

1 indicates the array was successfully initialized, 



lamskb 



The name of a 4-word array. This array allows the use of 
multiple LPAll-Ks within the same program, since the LUN is 
specified in the first word of the array. Refer to the 
description of the LAMSKS routine. 

If compatibility with K-series software is desired, the default 
(LUN 7) lamskb parameter should be used, and LUN 7 will be 
assigned to LAO: in the task-build command file for the user 
task. 

bufO, etc. 

The name of a buffer. A maximum of eight buffers can be 
specified. Any buffer names in excess of eight are ignored. At 
least two buffers must be specified to maintain continuous 
sampling . 

Each buffer specified in the call to SETIBF is assigned a number 
ranging from to 7. 

The assignment of these numbers is based on the order in which buffer 
names appear in the argument list. The first buffer whose name 
appears in the list is assigned number 0, the second is assigned 
number 1, and so forth. In all subsequent calls to other routines 
involving the set of buffers specified in a call to SETIBF, these 
numbers, rather than names, are used to refer to particular buffers. 



21.3.1.18 STPSWP: Stop Sweep - The STPSWP routine stops a sweep that 
is in progress. 

The STPSWP call is as follows: 

CALL STPSWP (ibuf [,iwhen] , [ind] ) 
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ibuf 

The 40-word array specified in the call that initiated a sweep. 

iwhen 

Specifies when to stop the sweep: 

stops the sweep, immediately aborting the sweep. This is 
the default stop method. The sweep will be stopped 
asynchronously by the LPAll-K hardware. When lOSB(l) 
equals 1, the sweep has been stopped. Call IWTBUF 
continously after calling STPSWP until the sweep has 
actually been stopped. When stopping (aborting) a sweep in 
this manner, the data contents of the current data buffer 
cannot be guaranteed. 

+n (any positive value) stops the sweep at the end of the 
current buffer. This is considered to be the normal means 
for stopping a sweep. 

-n (any negative value) is reserved. (Do not use.) 

ind 

Receives a success or failure code as follows: 

1 indicates that the sweep will be stopped (at the time 
indicated by iwhen) . 

indicates an illegal argument list. 

-n is a directive error code indicating that the stop sweep 
QIO failed. 



21.3.1.19 XRATE: Compute Clock Rate and Preset - The XRATE routine 
allows the user task to compute a clock rate and preset. The clock 
rate divided by the clock preset yields the desired dwell (intersample 
interval) . 



NOTE 

The XRATE routine can be used only on 
systems that have a FORTRAN or 
BASIC-PLUS-2 compiler. This module is 
not included with the other LPAll-K 
support routines in object module 
format. Rather, it is included in 
source code format with the K-series 
source modules in [45,10] on the system 
disk . 
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XRATE can be invoked as a subroutine or a function as follows: 

CALL XRATE (dwell , i rate , iprset , if lag ) 
or 

adwell = XRATEfdwell , irate, iprset, iflag) 



dwell 



The intersample time desired by the user. The time is expressed 
in decimal seconds (REAL*4) . 



irate 

Receives the computed clock rate as a value from 1 to 5. 



Lprset 

Receives the clock preset, 



iflag 



Specifies whether the computation is intended for Clock A or 
Clock B: 

indicates the computation is for Clock A. 
nonzero indicates the computation is for Clock B. 



adwell 



The actual dwell rate for the clock based on the irate and iprset 
parameters. 



21.3.2 MACRO-11 Interface 

The MACRO-11 interface to the LPAll-K consists of either the callable 
routines described in Section 21.3.1 or a set of device-specific QIO 
functions. 



21.3.2.1 Accessing Callable LPAll-K Support Routines - MACRO-11 
programmers access the LPAll-K support routines through either of two 
techniques: 

1. The standard subroutine linkage mechanism and the CALL op 
code 

2. Special-purpose macros that generate an argument list and 
invoke a subroutine 

These techniques are described in the following subsections. 
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21.3.2.2 Standard Subroutine Linkage and CALL Op Code - LPAll-K 
routines can be accessed through use of the standard subroutine 
linkage mechanism and the CALL op code. The format of this procedure 
is : 



.PSECT code 

MOV #arglist,R5 

CALL Isubr 



;ARGUMENT ADDRESS TO R5 
;CALL LPAll-K ROUTINE 



arglist : 



.PSECT data 
•BYTE narg,0 
.WORD addrl 



; NUMBER OF ARGUMENTS 

; FIRST ARGUMENT ADDRESS 



.WORD addrn 



;LAST ARGUMENT ADDRESS 



In this sample, the two PSECT directives are shown only to indicate 
the noncontiguity of the code and data portions of the linkage 
mechanism. Within the argument list, any argument that is to be 
defaulted must be represented by a -1 address (that is, 177777(8)). 



21.3.2.3 Special-Purpose Macros - To facilitate the calling of 
LPAll-K support routines from a MACRO-11 program, two macros are 
provided in file [45,10] LABMAC. MAC. These macros are: 

1. INITS 

2. CALLS 

INITS is an initialization macro. It must be invoked at the beginning 
of the MACRO-11 source module. 

CALLS invokes an LPAll-K support routine. The format of this macro 
call is as follows: 



CALLS Isubr ,<argl ,... ,argn> 



Isubr 



The name of an LPAll-K support routine, 



argl, and so forth 

Arguments to be formatted into an argument list and passed to the 
routine. Each argument can be either a symbolic name or a 
constant (interpreted as a positive decimal number) or can be 
defaulted. 
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An example showing the use of these macros is as follows; 



.TITLE EXAMPLE 

.IDENT 701.00/ 

IBUF: .BLKW 40, 

ISTAT: .BLKW 5 

INITS ; INITIALIZATION 



START: 



FIND STATUS OF 5 SWEEP BUFFERS 
BEING USED IN CURRENT SWEEP 

CALLS IBFSTS (IBUF, ISTAT) 



.END 



START 



21.3.2.4 Device-Specific QIO Functions - Table 21-2 lists the 
device-specific functions of the QIO system directive macro that are 
available for the LPAll-K. Programmers using these functions are 
entirely responsible for buffer management (refer to Section 21.4) as 
well as all other interfaces (for example, the request descriptor 
array). Little (if any) performance improvement over the use of 
FORTRAN support routines can be expected by using QIOs. Therefore, it 
is recommended that routines described in Section 21.3.1 be used. 



Table 21-2 
Device-Specific QIO Functions for the LPAll-K 



QIO Function 


Purpose 


lO.CLK 


Start clock 


10. INI 


Initialize LPAll-K 


lO.LOD 


Load microcode 


lO.STA 


Start data transfer 


lO.STP 


Stop request 

. 1 
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The MACRO-11 programmer must set up the appropriate Request Descriptor 
Array (RDA) before the corresponding QIO request is issued. In the 
case of the lO.STA function (start data transfer), the RDA is set up 
with buffer virtual addresses. The LPAll-K driver address checks and 
relocates these buffers, changing them from single-word to double-word 
addresses. The RDA is fully described in the source code of the 
driver . 



21.3.2.5 lO.CLK - The lO.CLK function writes an image ihto the 
LPAll-K real-time clock control register and issues a clock start, 
command. The format of the QIO request is: 

QIO$C lO.CLK, . . , ,<mode,ckcsr ,preset> 

mode 

The mode. 



ckcsr 



The image to be written into the clock control register. To 
achieve the function of clock rate -1 (see Section 21.3.1.2) for 
Clock A only, set a clock rate of and set the Schmitt Trigger 1 
Interrupt Enable bit in the Clock A Status Register. 



preset 

The clock preset, 



21.3.2.6 10. INI - The lO.INI function initializes the LPAll-K. The 
task issuing the QIO request must be privileged. The format of the 
request is as follows: 

QIO$C lO.INI, , .. ,<irbuf ,278.> 



irbuf 



A buffer containing an LPAll-K initialize RDA. The buffer size 
must be at least 278 (10) bytes. 



21.3.2.7 lO.LOD - The lO.LOD function loads a buffer of LPAll-K 
microcode. The issuing task must be privileged. The function 
verifies that there are no active users for the LPAll-K and resets the 
hardware. It then loads and verifies the microcode, starts the 
LPAll-K, and enables interrupts. The function returns to the issuing 
task when the Ready Interrupt is posted. 
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The format of the QIC request for the lO.LOD function is as follows; 
QIO$C lO.LOD, . . . ,<mbuf ,2048.> 



mbuf 



A buffer containing microcode to be loaded. The buffer size must 
be 2048(10) bytes. 



21.3.2.8 lO.STA - The lO.STA function issues an LPAll-K data transfer 
start command. The format of the QIO request is: 



QIO$C lO.STA, . . . ,<bufptr,40.> 

bufptr 

A pointer to a buffer containing an LPAll-K sample start RDA. 
The buffer size must be at least 40(10) bytes. 

The subfunction codes defined for the lO.STA function are: 

Bit 0=0 indicates that an AST is to be generated for every 
buffer (if an AST is specified). 

Bit 0=1 indicates that an AST is to be generated only for 
exception conditions. 



21.3.2,9 lO.STP - The lO.STP function stops a data transfer request. 
The issuing task must be the same task that initiated the data 
transfer. The format of the QIO request is as follows: 

QIO$C lO.STP, . . . ,<userid> 



userid 



The index number associated with the user whose request is to be 
stopped . 



21.3.3 The I/O Status Block (lOSB) 

Each active sweep must have its own I/O status block. The I/O status 
block (lOSB) is a 2-word array allocated in the user program. It is 
used to receive the status of a call to an LPAll-K support routine. 
When a data sweep routine is called, the lOSB is always the first two 
words of the 40-word array specified as the first argument of the 
call. The first word of the lOSB contains the status code, and the 
second word contains the buffer size in words. 
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NOTE 



The 2-word lOSB is not directly used by 
the LPAll-K driver. Instead, the driver 
uses a 4-word lOSB for internal 
communications with support routines; 
this 4-word lOSB is completely 
transparent to FORTRAN support routine 
users. However, when issuing QIOs, it 
is the 4-word lOSB that must be 
referenced. 

The first two words of the 4-word lOSB 
function as a 2-word overall lOSB for 
returning QIO completion status. The 
driver returns status such as sweep 
done, system errors, and LPAll-K 
hardware errors with this 2-word portion 
of the lOSB. 



The remaining two words function as an 
intermediate lOSB for passing status 
information during the data sweeps. 
MACRO-11 programs using QIO calls always 
receive the correct 2-word portion of 
the lOSB in the AST generated by the 
LPAll-K driver. 



The codes that can appear in the first word of an I/O status block are 

in ISA-compatible format (with the exception of the I/O pending 

condition). Table 21-3 lists all return codes (except 351; see 
Section 21. 5) . 



lOSB(l) 



FORTRAN 





1 
301 
302 
303 
304 

305 



MACRO 



I . PND 

IS. sue 

IE. BAD 
lE.IFC 
lE.DNR 
lE.VER 

lE.ULN 



Table 21-3 
Contents of First Word of lOSB 



Meaning 



Operation pending; I/O in progress 

Successful completion 

Invalid arguments 

Invalid function code 

Device not ready (See Section 21.7) 

Unrecoverable hardware error caused by 
power-fail 

LUN not assigned to LPAll-K 



(continued on next page) 
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Table 21-3 (Cont.) 
Contents of First Word of lOSB 



lOSB(l) 



FORTRAN MACRO 



306 
309 
313I 
315I 

316 

317I 

320 

323 

359I 

366 

397 



lE.SPC 
IE. DUN 
I E . DAO 
I E.ABO 

lE.PRI 
lE.RSU 
lE.BLK 
IE. NOD 
lE.FHE 
lE.BCC 
lE.IEF 



Meaning 



Illegal buffer specification 

Insufficient UMRs available for request 

Data overrun 

Request terminated; LPAll-K status code in 
I0SB(2) 

Privilege violation 

Resource in use (load microcode only) 

Executive blocked driver waiting for UMRs 

System dynamic memory exhausted 

Fatal hardware error on device 

LPAll-K load microcode error 

Invalid event flag specified 



1. I0SB(2) contains an LPAll-K status code. Refer to the LPAll-K 
User's Manual for explanation of status code. 



21.4 BUFFER MANAGEMENT 

The management of buffers for data transfers by LPAll-K support 
routines involves the use of two FIFO (First-In, First-Out) queues: 

1. The device queue (DVQ) 

2. The user queue (USQ) 

The device queue (DVQ) contains the numbers of all buffers that the 
user task has released to the support routines in a call to RLSBUF. 
The buffers represented by these numbers are ready to be filled with 
data (input sweeps) or to be emptied of data (output sweeps). Any 
buffer specified in a call to INXTBF must already be in DVQ. 

The user queue (USQ) contains the numbers of buffers available to the 
user task. For output sweeps, this queue contains the numbers of 
buffers that have already been emptied by the driver. For input 
sweeps, the buffers represented by USQ are those which are filled with 
data. In both instances, the user task determines the next buffer to 
use (that is, it extracts the first element of USQ) by calling IGTBUF 
or IWTBUF. 
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Both the DVQ and USQ are initialized to -1 — indicating no 
buffers — when the user task calls the SETIBF routine. The user task 
must call RLSBUF before initiating any sweep, since at least one 
buffer must be present in DVQ for the first input or output to occur. 

For input sweeps, it is recommended that the user task call RLSBUF, 
specifying the numbers associated with all the buffers to be used in 
the sweep. 

For output sweeps, the user task can specify two buffers (for 
continuous sweeps) in the call to RLSBUF. The first action then taken 
either in a completion routine or after a call to IWTBUF is to release 
the next buffer. However, note that this approach does not represent 
true multiple buffering since data overrun occurs if the second buffer 
is not released in time. 

If a buffer overrun occurs, the LPAll-K normally aborts the affected 
sweep and returns an appropriate error code. However, the option of 
having buffer overruns treated as nonfatal error conditions can be 
selected by specifying the appropriate mode argument in any of the 
sweep calls. Then, when a buffer overrun occurs, the LPAll-K 
automatically defaults to buffer for its next data buffer. In this 
case, the following special considerations regarding buffer management 
must be observed. 

Call RLSBUF* before calling any of the sweep control calls. However, 
if buffer overruns are to be treated as nonfatal conditions, the task 
should not specify buffer in the initial call to RLSBUF. (It is 
assumed at the outset that buffer is available for use in this 
manner and, therefore, should not be released.) 

Once a buffer overrun has occurred,- buffer is used by the LPAll-K 
and placed on the user queue just like any other data buffer. At this 
point, buffer is no longer available for buffer overruns. The task 
then removes buffer from the user queue by IWTBUF or IGTBUF for 
possible processing. It is the task's responsibility to release 
buffer for future buffer overruns by specifying buffer in a call 
to RLSBUF. Note that the task cannot determine that buffer overrun 
occurred until it receives buffer from IWTBUF or IGTBUF. 

The LPAll-K always uses buffer following a buffer overrun if that 
condition was specified as nonfatal. Thus, when a second buffer 
overrun occurs before buffer has been processed and made available 
for that purpose, a condition called "double buffer overrun" occurs. 
In this case, buffer is not put on the user queue since the actual 
contents of buffer cannot be determined at this time, and buffer 
may actually still be on that queue. The double buffer overrun 
condition is detected when the task attempts to make buffer 
available for future buffer overruns with the call to RLSBUF. Note 
that_ this is the first time that the task is notified of the 
condition. If a double buffer overrun condition is detected during 
the call to RLSBUF, the task must be notified of the condition 
indicating that the previous processing of buffer contents may have 
been of no value (the LPAll-K probably changed the buffer's contents 
while it was being processed). 
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21.5 LOADING THE LPA-11 MICROCODE 

LAINIT is a privileged task that is used to load all versions of 
LPAll-K microcode. When called, LAINIT issues an lO.LOD function in a 
QIO request, followed by 10. INI and lO.CLK function requests. The 
lO.CLK function starts the clock with a default clock rate of 1 MHz. 

During SYSGEN Phase 1, a command file is generated with LPAll-K 
support selected through operator response to SYSGEN questions. 
During SYSGEN Phase 2, the command file builds LAINIT using additional 
information obtained through operator response to SYSGEN questions. 
This information further defines the LPAll-Ks system environment and 
characteristics for the specific user application. 

Separate tasks are built during SYSGEN that invoke LAINIT to load 
appropriate LPAll-K microcode. These tasks are named LAINn, where n 
corresponds to unit number (starting with unit number 0) for each 
LPAll-K unit in the system. Thus, LAINIT is never directly invoked by 
the user. 

SYSGEN automatically generates command lines in SxSVMR.CMD that will 
install LAINIT and LAINO; LAINl and subsequent LPAll-K unit-numbered 
tasks are not automatically included in the command file. Thus, the 
user must install these tasks (if they are required) with VMR or MCR. 

Once LAINIT and LAINn tasks have been installed, a particular version 
of LPAll-K microcode for a specific unit can be loaded by running the 
corresponding LAINn task. For example: 

>RUN LAIN2 

executes LAIN2, loading microcode for LPAll-K unit 2. 

When a power-fail recovery occurs, the LPAll-K driver terminates all 
outstanding activity and requests execution of initiating task(s) 
(LAINn) for each unit. This automatically provides power-fail 
recovery for the LPAll-K microprocessor, provided the LAINIT and LAINn 
tasks are installed. Note that when either the RSX-llM system is 
bootstrapped or the LPAll-K driver is loaded, a simulated power-fail 
(resulting in driver power-fail recovery) occurs, loading microcode 
for each LPAll-K unit. In addition, when the LPAll-K is brought 
online on an RSX-llM-PLUS system, a simulated power-fail occurs. 

If the request for the initiating task (LAINn) fails or the loader 
fails to load the driver, the LPAll-K unit does not become 
initialized. Any further attempt to use the LPAll-K will fail, with 
the device not ready (lE.DNR) code returned to the requesting task. 

If there is no LPA-llK present at the default address, LAINx returns 
error code 351 in lOSB(l). This failure occurs if there is more than 
one LPA-llK and the one at the default address is removed. There must 
always be an LPA-llK at the default address. 
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All versions of LAINn set the real-time clock frequency to IMHz by 
default. The UCB device characteristics word 4 (U.CW4) contains a 
15-bit buffer preset value that controls the rate of ticks (that is, 
the rate at which the clock interrupts) . This value can be set 
dynamically or during SYSGEN. The quotient resulting when this value 
is divided into 1 MHz is the rate of ticks. For example, if U.CW4 
contains 2, the tick rate is 500kHZ. The user can issue a Get LUN 
Information system directive to examine the preset value and the MCR 
SET /BUF command can be used to modify it while the system is running. 
This modification will take effect the next time the LPAll-K is 
reloaded with micro-code by LAINx. 
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In order to attain maximum LPAll-K performance, the LPAll-K driver is 
designed to appear not busy to the RSX-llM/M-PLUS Executive. As a 
result, the potential problem exists that any privileged user can 
unload the driver while the LPAll-K is servicing other users. 
Therefore, the user must first determine that the LPAll-K is not being 
used prior to unloading the driver. 



21.7 TIME-OUT OF THE LPAll-K 

The error code lO.DNR means that the LPAll-K timed out while 
processing a user request. In dedicated mode, this condition can have 
special meaning. 

The LPAll-K driver (LADRV) disables the time-out countdown following 
LPAll-K acknowledgement of the user-task request. In all cases in 
multirequest mode, and in most cases in dedicated mode, this 
acknowledgement is received almost immediately after the user-task 
request is passed to the LPAll-K. The only case when this is not true 
is when the user task requests that a data sweep be started while in 
dedicated mode. In this case, the LPAll-K waits to transfer the first 
256 words of data before acknowledging the sweep request. 

If a task is sampling at extremely slow data rates in dedicated mode, 
the time to transfer that first 256 words may exceed the time-out 
count for the device. This can be avoided by using the multirequest 
mode. 

If a task must use dedicated mode for high sampling rates, and the 
start of the sweep will be delayed for an extended period of time, the 
time-out count for the LPAll-K must be disabled. (Refer to the note 
in LADRV describing this time-out problem and showing where the 
time-out can be safely disabled for sweep calls.) 

NOTE 

This procedure will disable the 
detection of real time-outs for sweep 
calls in dedicated mode. 
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21.8 22-BIT ADDRESSING SUPPORT 

The LPAll-K driver supports 22-bit addressing on systems having that 
capability. When the system employs 22-bit addressing, certain 
restrictions are imposed. As a result, tasks written for use with 
earlier LPAll-K driver versions may not run without user task 
modifications. These restrictions are discussed in the remainder of 
this section. 

When the LPAll-K driver is executed on 22-bit systems, a certain 
contiguity of user-task data structures must be established. The task 
data transfer buffers and the IBUF array must be contiguous. In 
addition, the task random channel list (if present) and the last data 
transfer buffer must be contiguous. Thus, the correct sequence for 
user-task data is the IBUF array, followed by the task data transfer 
buffers, followed by the task random channel list. Failure to 
structure the user-task data in this manner can result in illegal 
buffer specification errors (lE.SPC) being returned or possible 
corruption of task address space by data sweeps. 

Since the LPAll-K user task can potentially request more buffer space 
than there is UMR mapping space, a limit on the total number of UMRs 
that can be used by the LPAll-K driver at any time must be specified. 
This limit is specified during SYSGEN part 1, along with the interrupt 
vector and CSR address for the LPAll-K. 

If a task's UMR requirements will cause the total number of UMRs 
currently in use by the LPAll-K to exceed the SYSGEN-specif ied limit, 
the task will receive an Insufficient UMRs Available For Request 
(IE. DUN) error code in lOSB(l) of the IBUF array. 

This condition can be avoided by setting the UMR limit to the expected 
minimum number required for smooth LPAll-K operation for all expected 
users. Since each UMR maps 8K bytes, each user's requirements can be 
calculated as follows: 

• Each IBUF array requires 76(10) bytes of UMR mapping. 

• Add this result to the byte length of all the contiguous 
transfer buffers to be used in the sweep. 

• Add this result to the byte length of the random channel list 
(if it exists) . 

• The number of UMRs the user task needs is the total byte count 
divided by 8192 (8K) and rounded up to the next 8K (if not an 
exact multiple of 8192) . 

Because there are only 31 UMRs available for the entire system, it is 
not desirable to allow the LPAll-K driver (through the 
SYSGEN-specif ied limit) to have access to all or nearly all UMRs at 
any given time. Since other device drivers may also require UMR 
mapping, the total allocation of UMRs by LADRV can slowly choke a 
system, and for that reason allocation of UMRs must be carefully 
considered. 
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The UMR allocation limit for the LPAll-K can be changed by directly 
modifying the value in the LPAll-K's UCB word U.LAUB; it is not 
necessary to do another SYSGEN. Use the OPEN command to access and 
change the limit to the new value. Possible values can range from 
0-31. Then, make the required change, UNLOAD, and then LOAD the 
LPAll-K driver. If the LPAll-K driver is resident, the value in 
U.LAUB+2 must also be changed to the new value. 

NOTE 

Be sure the LPAll-K is Idle before 
attempting to access the UCB. 

It is possible for a condition to exist where there may not be enough 
UMRs available for the Executive to allocate to the driver at the time 
the request is made, even if the number of UMRs necessary to map the 
user task's request are within the SYSGEN-def ined limit. When this 
happens, the _ Executive blocks the driver until its UMR request can be 
granted. Since this condition can introduce sweep timing errors, the 
current sweep is unconditionally aborted and an appropriate error code 
(IE. ELK) is returned to the task in lOSB(l). 



21.9 SAMPLE PROGRAMS 

C LPAll-K SAMPLE PROGRAM 

C 

C SAMPLE SHOWS THE BASIC FLOW FOR PROGRAMMING THE LPAll-K IN A HIGHER 

C LEVEL LANGUAGE. IT IS EXPECTED THE USER WILL TEST lOSB RETURNS AND 

C ERROR INDICATORS (IND) AS NECESSARY. SYNCHRONOUS PROGRAM TERMINATION 

C IS SUGGESTED. NOTE: THIS SAMPLE PROGRAM WILL NOT EXECUTE CORRECTLY IN 

C 22-BIT MODE 

C 

C D/A DEDICATED MODE WITH CONTINUOUS SAMPLING 

C 

C PROGRAM RUNS 3 LOOPS (BASED ON NCNT) . ON FIRST LOOP, 

C STOPS SYNCHRONOUSLY AT END OF PRESENT BUFFER WHICH HAPPENS 

C TO BE BUFFER #3 BEING FILLED FOR THE 2ND TIME. 

C THE 2ND LOOP TERMINATES ASYNCHRONOUSLY (IWHEN=0). 

C THE 3RD LOOP TERMINATES ASYNCHRONOUSLY ALSO. 

C 

C 

DIMENSION IBUF(40) ,I0SB(2) ,NB(1024,8) 

EQUIVALENCE ( IBUF ( 1 ) , lOSB ( 1 ) ) 

EQUIVALENCE (NO , NB ( 1 , 1 ) ) , (Nl ,NB ( 1 , 2) ) , (N2 , NB ( 1 , 3) ) , (N3 , NB ( 1 , 4) ) 

EQUIVALENCE (N4 ,NB ( 1 , 5) ) , (N5 ,NB ( 1 , 6) ) , (N6 ,NB (1 , 7) ) , (N7 ,NB (1 , 8) ) 

CALL CLOCKA (4,-1) 

IWHEN=1 

NCNT=0 
2 ICNT=1 

5 CALL SETIBF(IBUF,IND, ,N0,N1,N2,N3) 
C 

C INITIALIZE BUFFERS TO ALL -2'S 
C 

DO 10 J=l,8 

DO 10 K=l,1024 
10 NB(K,J)=-2 

CALL RLSBUF(IBUF,IND,1,2,3) 

CALL DASWP(IBUP,1024,,,,20) 
20 CALL IWTBUF(IBUF,20,IBUFNO) 

CALL RLSBUF ( IBUF, IND, IBUFNO) 

WRITE (1,300) IBUFNO, lOSB(l) ,I0SB(2) ,ICNT 

IF (NCNT.EQ.3) GOTO 40 
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IF (ICNT.EQ.6) GOTO 2 

ICNT=ICNT+1 

IF (ICNT.NE.4) GOTO 20 

CALL STPSWP (IBUF,IBUFNO) 

IWHEN=0 

NCNT=NCNT+1 

GOTO 20 
40 CALL IGTBUF(IBUF,IBUFNO) 

WRITE (1,300) IBUFN0,I0SB{1) ,I0SB(2) ,ICNT 
300 FORMAT ( 3X, 110 , 208 , 110) 

STOP 

END 

The following sample program will test the digital I/O interface of 
the LPAll-K. It will execute correctly in 22-bit mode. 

C 

C PROGRAM TO TEST DIGITAL INPUT AND OUTPUT FOR LPAll-K 

C DIGITAL EQUIPMENT CORPORATION 

C 

C THIS PROGRAM IS DESIGNED TO OUTPUT A DATA BUFFER TO THE LPAll-K 

C DIGITAL I/O INTERFACE AND AT THE SAME INSTANT FOR EACH SAMPLE 

C WORD READ THE RESULTS BACK. THE DATA BUFFERS ARE COMPARED TO 

C MAKE SURE THE TRANSFER IS COMPLETED SUCCESSFULLY. 

C 

Q ****** NOTE' ****** 

C THIS PROGRAM WILL WORK IF AND ONLY IF THE DIGITAL I/O 

MODULE 

C UNIT SPECIFIED HAS THE MAINTENANCE JUMPER "WRAP-AROUND" 

CABLE 

C INSTALLED ! ! ! ! 

C 

C 

C RESERVE STORAGE FOR LPAll-K ROUTINES 

C 

C THIS PROGRAM WILL WORK IN 22-BIT MODE 

C 

C DATA BUFFERS 

C 

INTEGER*2 IBUFI (40) , INBUF ( 300 , 4) 

INTEGER*2 COMMI(1240) 

EQUIVALENCE (IBUFI (1) ,C0MMI(1) ) 

EQUIVALENCE (INBUF (1,1) ,COMMI (41) ) 

INTEGER*2 IBUFO(40) ,OUTBUF ( 300 , 4) 
INTEGER*2 COMMO(1240) 
EQUIVALENCE(IBUF0(1) ,C0MM0(1) ) 
EQUIVALENCE(0UTBUF(1,1) ,C0MM0(41) ) 

C RESERVE STORAGE AND EQUIVALENCE FOR RSX I/O STATUS BLOCKS 

LOGICAL*! INI0S(4) ,0UTI0S(4) 

EQUIVALENCE (IBUFO(l) ,0UTI0S(1) ) , (IBUFI (1) ,INI0S(1) ) 
C 

C SET BUFFER SIZE TO USE FOR THIS REQUEST - MAXIMUM OF 300 
WITHOUT 
C CHANGING THE DIMENSION STATEMENTS. MUST BE EVEN! 

ISIZE=300 
C 
C INITIALIZE THE PASS COUNTER FOR THE LOOP 

IPASS=1 
C 
C SET LPAll-K LOGICAL UNIT NUMBER AND ASSIGN IT TO LAO: 

ILUN=7 

CALL ASSIGN (ILUN, 'LA: ' ,0,ISTAT) 

IFdSTAT .LT, 0)GO TO 100 
C 
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C INITIALIZE THE OUTPUT DATA BUFFER 

DO 2 J=l,4 

DO 2 I=1,ISIZE,2 

OUTBUF(I,J)="125252 

0UTBUF(I+1, J) ="052525 
2 CONTINUE 
C 

C STOP LPAll-K REAL TIME CLOCK "A" THIS WILL MAKE SURE THAT 
C NOTHING HAPPENS WHEN WE INITIALIZE THE TWO SWEEPS. 
5 CALL CLOCKA(0,0,ISTAT,ILUN) 

IF(ISTAT .NE. 1)G0 TO 110 

C INITIALIZE THE INPUT DATA BUFFER. ASSUME THE LPAll-K DIGITAL 

C I/O INTERFACE IS CONFIGURED IN THE DATA LATCH MODE (AS OPPOSED 

C TO SENSE) . THUS THE OUTPUT DATA BUFFER MUST CONTAIN A BIT 

CHANGE 

C FOR EVERY BIT POSITION IN SUCCEEDING DATA WORDS. 

DO 10 J=l,4 

DO 10 I=1,ISIZE 

INBUF(I,J)=0 
10 CONTINUE 
C 

C INITIALIZE DIGITAL OUTPUT SWEEP. THIS MUST BE DONE BEFORE INIT 
C OF DIGITAL INPUT SWEEP! THE LPAll-K PROCESSES THE TRANSFER OF 
C DATA IN THE ORDER OF THE SPECIFICATION OF THE SWEEPS. THUS WE 
C WANT TO OUTPUT BEFORE WE INPUT. 

CALL 
SETIBF(IBUFO,ISTAT, ,0UTBUF(1,1) ,0UTBUF(1,2) ,0UTBUF(1,3) , 

1 0UTBUF(1,4)) 

IFdSTAT .NE. 1)G0 TO 120 
C 

C RELEASE BUFFER FOR OUTPUT SWEEP 
C ALL FOUR BUFFERS — INDEXES 0,1,2,3 — ARE RELEASED 

CALL RLSBUF(IBUFO,ISTAT,0,1,2,3) 

IFdSTAT .NE. 1)G0 TO 130 
C 

C "START" DIGITAL OUTPUT SWEEP. REMEMBER NOTHING WILL HAPPEN 
UNTIL 

C WE START THE REAL TIME CLOCK. THE LPAll-K WILL PROCESS THE 
REQUEST 

C AND BE ALREADY TO TRANSFER DATA WHEN WE RESUME THE CLOCK. 
C EVENT FLAG 14 IS SPECIFIED. A DIFFERENT EVENT FLAG MUST BE 
C SPECIFIED FOR THE DIGITAL INPUT SWEEP SO THE FORTRAN PROGRAM 
C CAN SYNCHRONIZE WITH TWO INDEPENDENT, ASYNCHRONOUS PROCESSES. 

CALL DOSWP(IBUFO,ISIZE,4,0,1,14,30,0) 
C 
C 

C NOW INITIALIZE FOR DIGITAL INPUT SWEEP. THE SAMPLING 
PARAMETERS 

C MUST BE THE SAME FOR BOTH THE INPUT AND OUTPUT SWEEP. WE WANT 
C TO WRITE AND READ THE SAME DATA WORD AT THE SAME TIME. 

CALL 
SETIBF(IBUFI,ISTAT,,INBUF(1,1) ,INBUF(1,2) ,INBUF{1,3) , 

1 INBUF(1,4)) 

IFdSTAT .NE. 1)G0 TO 140 
C 
C RELEASE THE INPUT BUFFERS 

CALL RLSBUF(IBUFI,ISTAT,0,1,2,3) 

IFdSTAT .NE. 1)G0 TO 150 
C 

C "START DIGITAL OUTPUT SWEEP. AGAIN, NOTHING WILL HAPPEN UNTIL 
C WE RESUME THE LPAll-K REAL TIME CLOCK. 

C EVENT FLAG 15 IS SPECIFIED TO SEPARATE THE INPUT AND OUTPUT 
SWEEPS. 

CALL DISWP(IBUFI,ISIZE,4,0,1,15,30,0) 
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C NOW FOR THE BIG EVENT! WE START THE CLOCK AND SEE WHAT HAPPENS. 

CALL CLOCKA(1,-150,ISTAT,ILUN) 

IF(ISTAT .NE. 1)G0 TO 150 
C 
C 

C THE LPAll-K SHOULD NOW BEGIN TO TRANSFER DATA 

C FIRST WE WAIT FOR THE DIGITAL OUTPUT SWEEP TO FINISH. IT WAS 
C STARTED FIRST AND SHOULD FINISH FIRST. WE VERIFY THAT IT 
C FINISHES CORRECTLY OR CHECK FOR ERRORS. 
15 CALL IWTBUF(IBUF0,14,IBUFN0) 
C 

C IF BUFFER NUMBER IS -1, THEN ERROR 
C IF BUFFER NUMBER IS 0,1, OR 2, THEN CONTINUE 
C IF BUFFER NUMBER IS 3, THEN FINISHED 

IF(IBUFNO .LT. 0) GO TO 160 
C 

C NOW WAIT FOR THE DIGITAL INPUT SWEEP TO FINISH. THE SAME ERROR 
C CONDITIONS APPLY. 

CALL IWTBUF(IBUFI,15,IBUFN0) 

IF(IBUFNO .LT. 0)GO TO 170 

IF(IBUFNO .LE. 2)G0 TO 15 
C 

C THE FACT THAT WE HAVE GOTTEN HERE SAYS THE LPAll-K HAS DONE ITS 
C THING. 
C CHECK THE INPUT DATA BUFFERS AGAINST THE OUTPUT DATA BUFFERS 

DO 20 J=l,4 

DO 20 I=1,ISIZE 

IF(INBUF(I,J) .NE. OUTBUF(I,J) )G0 TO 180 
20 CONTINUE 
C 

C SUCCESSFUL COMPLETION, LET EVERYONE KNOW. THEN GO BACK AND DO 
IT 
C AGAIN. 

WRITE(5,1000)IPASS 
1000 FORMATC REQUEST COMPLETE !', 2X, 16) 

IPASS=IPASS+1 

GO TO 5 
C 

C REPORT ANY ERRORS THAT HAVE BEEN UNCOVERED IN THE EXAMPLE. 
C 

100 WRITE(5,1010) ISTAT 
1010 FORMAT(//,' ERROR ASSIGNING LUN TO LPAll-K ',16) 

CALL EXIT 
110 WRITE(5, 1020) ISTAT 
1020 FORMAT(//,' ERROR STOPPING LPAll-K CLOCKA ',16) 

CALL EXIT 
120 WRITE(5, 1030) ISTAT 
1030 FORMAT (//,' ERROR FROM SETIBF - OUTPUT BUFFER ',16) 

CALL EXIT 
130 WRITE(5,1040)ISTAT 
1040 FORMATC//,' ERROR FROM RLSBUF - OUTPUT BUFFER ',16) 

CALL EXIT 
140 WRITE(5, 1050) ISTAT 
1050 FORMAT(//,' ERROR FROM SETIBF - INPUT BUFFER ',16) 

CALL EXIT 
150 WRITE(5, 1060) ISTAT 
1060 FORMAT (//,' ERROR FROM RLSBUF - INPUT BUFFER ',16) 

CALL EXIT 
160 WRITE(5,1070) IBUFNO, (OUTIOS(I) ,1=1,4) 
1070 FORMAT(//,' ERROR FROM DOSWP ' , 12, 4 (3X, 04) ) 
r 

C *** WARNING *** DISWP MIGHT STILL BE ACTIVE WHEN YOU EXIT 
C 

CALL EXIT 
170 WRITE (5, 1080) IBUFNO, ( INIOS ( I ) , 1=1 , 4 ) 
1080 FORMAT(//,' ERROR FROM DISWP ' , 12 , 4 (3X, 04) ) 
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C 

C *** WARNING *** DOSWP MIGHT STILL BE ACTIVE WHEN YOU EXIT 
C 

CALL EXIT 
180 WRITE(5,1090)I,J,OUTBUF(I,J) ,INBUF(I,J) 
1090 FORMAT(//,' *DATA ERROR* - WORD # ',14 , 2X, 14 , 4X, 06 , 2X, 06) 

CALL EXIT 

END 
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K-SERIES PERIPHERAL SUPPORT ROUTINES 



22.1 INTRODUCTION 

K-series laboratory peripheral modules are supported through a set of 
program-callable routines that are linked with the user's task at 
task-build time. These routines are highly modular. Therefore, a 
particular task contains only that code necessary for the facilities 
actually used. Additionally, the support routines perform input and 
output operations through the Connect to Interrupt Vector (CINT$) 
Executive directive. This directive allows the user's task to bypass 
normal QIC processing and perform I/O almost completely independent of 
the Executive. 

The following subsections briefly describe the K-series laboratory 
peripherals, the features provided by the K-series support routines, 
and the generation and use of these routines. 



22.1.1 K-Series Laboratory Peripherals 

The K-series peripheral support routines provide single-user, 
task-level support for the following laboratory peripheral modules: 






AAll-K D/A converter 

ADll-K A/D converter 

AMll-K multiple gain multiplexer 

DRll-K digital I/O interface 

KWll-K dual programmable real-time clock 

AAVll-A D/A converter (LSI-11-bus-compatible) 

ADVll-A A/D converter (LSI-11-bus-compatible) 

DRVll parallel line unit (LSI-11-bus-compatible) 

KWVll-A programmable real-time clock (LSI-11-bus-compatible) 
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The maximum supported hardware configuration consists of one KWll-K 
and sixteen of each of the AAll-K, ADll-K (with optional AMll-K) , and 
DRll-K modules. The minimum configuration, if synchronous sweeps are 
desired, would be one KWll-K and any one of the three other modules. 
A single DRll-K supports nonclocked, interrupt-driven I/O sweeps or 
single digital input or output. A single ADll-K supports single-word 
A/D input and nonclocked, overflow-driven sampling (provided that the 
A/D conversion is started with the EXT start input on the ADll-K) . An 
AAll-K supports burst mode output and scope control. 



22.1.1.1 AAll-K D/A Converter - The AAll-K includes four 12-bit 
digital-to-analog converters (DACs) and an associated display control. 
The display control permits the user to display data in the form of a 
4096 X 4096 dot array. Under program control, a dot may be produced 
at any point in this array, and a series of these dots may be 
programmed sequentially to produce graphical output. The display 
control may output to chart or X/Y recorder or CRT display unit. 

The AAVll-A is an LSI-11-bus-compatible D/A converter with 
characteristics similar to those of the AAll-K. 



22.1.1.2 ADll-K A/D Converter - The ADll-K is a 12-bit successive 
approximation converter that enables the user to sample analog data at 
specified rates and to store the equivalent digital value for 
subsequent processing. The basic subsystem consists of an input 
multiplexer (switch-selectable between 16-channel single-ended or 
8-channel differential) , sample-and-hold circuitry, and a 12-bit A/D 
converter. By changing jumpers, the analog inputs can be made bipolar 
or unipolar. 

The ADVll-A is an LSI-11-bus-compatible D/A converter with 
characteristics similar to those of the ADll-K. 



22,1.1.3 AMll-K Multiple Gain Multiplexer - The AMll-K is a 
multiplexer expander that supplements the 16-channel single-ended (8 
differential) analog input multiplexer in the ADll-K. The expansion 
is done in three independent groups on the AMll-K. Each group can be 
set to 16 single-ended or pseudo-differential or 8 differential input 
channels; each group can have a gain of 1, 4, 16, or 64 assigned to 
it by a switch in the amplifier. 



22.1.1.4 DRll-K Digital I/O Interface - The DRll-K is a 
general-purpose digital input/output interface capable of the parallel 
transfer of up to 16 bits of data, under program control, between a 
PDP-11 UNIBUS computer and an external device (or another DRll-K) . 

The DRVll is an LSI-11-bus-compatible, general-purpose input/output 
interface with characteristics similar to those of the DRll-K. 
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22.1.1.5 KWll-K Dual Programmable Real-Time Clock - The KWll-K is a 
dual programmable real-time clock option used in PDP-11 UNIBUS 
computers. Features include: 

Clock A 

16-bit counter 

16-bit programmable preset/buffer register 

Four modes of operation 

Two external inputs (Schmitt triggers) 

Eight clock rates, program selectable 

Five clock frequencies, crystal controlled for accuracy 

Processor actions synchronized to external events 
Clock B 

8-bit counter 

8-bit programmable preset register 

Repeated interval mode of operation 

One external input (Schmitt trigger) 

Seven clock rates, program selectable 

Five clock frequencies, crystal controlled for accuracy 



The KWVll-A is an LSI-11-bus-compatible real-time clock with 
characteristics similar to those of the KWll-K. 



22.1.2 Support Routine Features 

The RSX-llM program-callable K-series support routines provide the 
following features: 

Clock overflow or trigger-driven A/D sweep 

Clock overflow or interrupt-driven digital input sweep 

Clock overflow or interrupt-driven digital output sweep 

Clock overflow or burst mode D/A sweep 

Single digital input 

Single digital output 

Single A/D input 
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• Scope control 

• Histogram sampling 

• Schmitt Trigger simulation 

• Clock control 

• 16-bit software clock 

• A/D input to real number conversion 

• Buffer control 

Immediate digital input or output can be performed at any time. 
Multiple clock-driven sweeps can be initiated if this optional feature 
was selected during the K-series generation dialog (see Section 
22,1,3.1). Such sweeps, however, are subject to the following 
restrictions: 

1, Regardless of the number of controllers present, there can be 
only one active A/D sweep at any point in time. The same 
restriction holds true for D/A sweeps. It is possible, 
however, to perform digital input and digital output sweeps 
simultaneously, using the same DRll-K, so long as this 
feature is selected during the generation dialog. 

2. There can be no conflict in clock rates among the sweeps. 

3. Only the first sweep can use the delay from start event, 

4, The interevent time data-gathering routine cannot run in 
parallel with any other clock-driven sweeps. 



22,1,3 Generation and Use of K-Series Routines 

To use K-series support routines, the user must do the following three 
things during SYSGEN: 

• Reserve necessary vector space. 

• Specify that the CINT$ Executive directive is to be included 
in the system. 

• Specify that AST support is required. 

At a point in time subsequent to SYSGEN, the user follows particular 
procedures for the following: 

1, Generation of K-series support routines 

2, Program use of K-series routines 

These two procedures are detailed in the following subsections. 
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22.1.3.1 Generation of K-series Support Routines - An indirect com- 
mand file, similar to those used for SYSGEN itself, is used to 
generate the K-series support routine library and other necessary 
facilities. This command file is invoked by typing the following: 

>@[200,200]SGNKLAB 

The dialog initiated by this command determines .the device 
configuration of the subsystem, the maximum number of buffers that 
will be used on a per-sweep basis, and the inclusion or omission of 
optional features such as multiple clock-driven sweeps and duplex 
digital I/O sweeps. 

After this information has been obtained, the command file creates the 

1. A prefix file, [45, 10] KPRE.MAC, for use during assembly of 
K-series support routines. 

2. A data base file, [45, 10] KIODT.MAC, containing control blocks 
needed to support the devices. 

3. A common block file, [45, 10]KCOM.MAC, that allows user tasks 
to access the I/O page. This file is used only on mapped 
systems. 

4. On mapped systems only, two indirect command files: 

a. [4 5, 24] KCOMBLD.CMD, which is a TKB build file for the 
common block 

b. [1,54] INSKCOM.CMD that is used to install the common 
block 

At the user's option, the K-series routines themselves can then be 
assembled and an object library created. The user can specify the 
name of this library or accept the following default file 
specification: 

LB: [1,1]KLABLIB.0LB 



22.1.3.2 Program Use of K-series Routines - The steps required for 
routine program use of K-series support routines are as follows: 

1. Compile or assemble the program. If the task will be 

overlaid, it is required that both the buffers used by the 

K-series support routines and the support routines themselves 

reside in the root section of the overlay structure. 
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Invoke TKB: 

a. On mapped systems only, use the /PR:0 switch to indicate 
that the task is privileged. 

b. Include the following indirect command among the 
responses to the TKB prompt: 

TKB>@ [1 , 5x] LNK2KLAB 

where x is for unmapped systems and 4 for mapped 
systems. 

c. On mapped systems only, enter the following indirect 
command in response to the prompt for options: 

ENTER OPTIONS 
@[l,54]LNK2KCOM 



// 

3. On mapped systems only, enter the following indirect command 
from a privileged terminal before executing the program: 

>@[l,54]INSKCOM 
The following is a complete example of the steps previously described: 

>F4P KTEST,KTEST/-SP=KTEST 

>TKB 

TKB>KTEST/PR:0,KTEST/-SP=KTEST, [1 , 1] F4P0TS/LB 

TKB>@[1,54]LNK2KLAB 

TKB>/ 

ENTER OPTIONS 

TKB>@[l,54]LNK2KCOM 



TBK>// 



22.2 THE PROGRAM INTERFACE 

A collection of program-callable subroutines provides access to the 
K-series laboratory peripherals. The formats of these calls are fully 
documented here for FORTRAN programs. MACRO-11 programmers access 
these same subroutines either through the standard subroutine linkage 
or through the use of two special-purpose macros. Both techniques are 
described in Section 22.2.2. Both FORTRAN and MACRO programs must 
contain at least one I/O Status Block (lOSB) , described in Section 
22.2.3, for retrieval of status information. 
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22.2.1 FORTRAN Interface 

Table 22-1 lists the FORTRAN interface subroutines for accessing 
K-series laboratory peripherals. 



Table 22-1 
FORTRAN Subroutines for K-series Laboratory Peripherals 



Subroutine 



ADINP 

ADSWP 

CLOCKA 

CLOCKS 

CVADF 

DASWP 

DIGO 

DINP 

DISWP 

DOSWP 

DOUT 

FLT16 

GTHIST 

IBFSTS 

ICLOKB 

IGTBUF 

INXTBF 

IWTBUP 

RCLOKB 

RLSBUF 

RMVBUF 

SCOPE 

SETADC 

SETIBF 

STPSWP 

XRATE 



Function 



Initiate single analog input 

Initiate synchronous A/D sweep 

Set Clock A rate 

Control Clock B 

Convert A/D input to floating point 

Initiate synchronous D/A sweep 

Digital start event 

Digital input 

Initiate synchronous digital input sweep 

Initiate synchronous digital output sweep 

Digital output 

Convert unsigned integer to a real constant 

Gather interevent time data 

Get buffer status 

Read 16-bit clock 

Return buffer number 

Set next buffer 

Wait for buffer 

Read 16-bit clock 

Release data buffer 

Remove buffer from device queue 

Control scope 

Set channel information 

Set array for buffered sweep 

Stop sweep 

Compute clock rate and preset 
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The calling sequences of the routines listed in Table 22-1 are 
compatible with the routines for the LPA-11, described in Chapter 21. 
The following subsections briefly describe the function and format of 
each FORTRAN subroutine call. 



22.2.1.1 ADINP: Initiate Single Analog Input - The ADINP routine 
obtains a single word as input from the A/D converter. 

ADINP can be invoked as a subroutine or a function as follows: 

CALL ADINP ( [iflag] , [ichan] ,ival) 
or 

ival=IADINP ( [iflag] , [ichan] , [ival] ) 

iflag 

The gain options: 

Absolute channel addressing (default) . This is the only 
mode supported on the ADVll (Q-bus) . 

1 Sample at a gain of 1. In modes 1, 2, 3, 4, and 5 each 
ADll-K/AMll-K is treated as 16 channels with channels 
17-63 strapped to gains 4, 16, and 64. The 48 
multiplexer channels are selected by the software 
according to the gain specification. Mode values 1, 2, 
3, 4, and 5 are not supported on the ADVll (Q-bus 
version) . 

2 Sample at a gain of 4. 

3 Sample at a gain of 16. 

4 Sample at a gain of 64. 

5 Perform auto gain ranging. 



ichan 



ival 



Selects the channel to be sampled. The default is 0. 



Receives the sample. The gain bits will be inserted if iflag is 
nonzero . 



22.2.1.2 ADSWP: Initiate Synchronous A/D Sweep - The ADSWP routine 
initiates a synchronous A/D input sweep through an ADll-K (and, if 
present, the AMll-K) . The analog input word placed in the user buffer 
consists of the 12 bits read from the A/D converter and (except when 
the mode parameter equals 0) the 2 gain bits read from the A/D status 

rtiyj.£3uet. rt va-LUtr uj- j.////ovo; j-S lcuulucu i-UJ. t\/ u L-j.me — ouu. t\ vaj.ut; 

of 177777(8) is returned on an A/D conversion error. Such errors are 
typically caused by conversions occurring too fast. 
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If differential input is desired, the channel increment must be set to 
2 by calling the SETADC routine. The default channel increment is 1 
(single-ended input) . 

NOTE 

This routine will expect to have the STl 
OUT from the KWll-K or similar trigger 
jumpered to EXT START on the ADll-K "if 
mode 512 is desired. This also requires 
the A EVENT OUT from the KWll-K clock 
trigger jumpered to the KW overflow on 
the ADll-K if clock driven sweeps are 
desired. 



The format of the ADSWP call is as follows: 

CALL ADSWP (ibuf ,lbuf , [nbuf] , [mode] , [iprset] , [iefn] , [Idelay] , 
[ichn] , [nchn] ) 



ibuf 



A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (lOSB). 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 0. 



nbuf 



The number of buffers to be filled. If nbuf is omitted or set 
equal to 0, indefinite sampling occurs. The STPSWP routine 
terminates indefinite sampling. 



mode 



Sampling options. The default is 0. The mode bit values listed 
below that are preceded by a plus sign (+) are independent and 
can be ADDed or ORed together. Those values not preceded by a 
plus sign are mutually exclusive and only one such value can be 
used at a time. All bit values not listed below are reserved. 

The following values can be specified: 

Absolute channel addressing (default) . This mode allows 
the user to directly access all 63 channels of an 
ADll-K/AMll-K combination. This is the only mode that 
is LPA-11 compatible. 
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1 Sample with a gain of 1. In modes 1, 2, 3, 4, and 5 
each ADll-K/AMll-K is treated as 16 channels with 
channels 17-63 strapped to gains 4, 16, and 64. The 48 
multiplexer channels are selected by the software 
according to the gain specification. Mode values 1, 2, 
3, 4, and 5 are not supported on the ADVll (Q-bus 
version) . 

2 Gain of 4. See also mode value 1. 

3 Gain of 16. See also mode value 1. 

4 Gain of 64. See also mode value 1. 

5 Driver will perform auto-gain ranging to return the 
result with the most significance. Note that use of 
auto-gain ranging may require dual sampling and will 
impact performance. See also mode value 1. 

7 Use user-supplied interrupt routine. The routine must 
be named .ADINU and must follow the interrupt service 
routine coding conventions used in this subsystem. 
Refer to the source module KADIN5.MAC for an example of 
an A/D interrupt routine. 

+256 External start (STl) . 

+512 Nonclock overflow sampling triggered by STl. 



iprset 



The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 
be used to calculate a clock preset value. If the iprset 
argument is omitted from the ADSWP call, the user must specify a 
mode value of +512. Otherwise, an error status code of 301 
(invalid arguments) is returned into the lOSB. 



iefn 



The event flag (1-96), a completion routine, or 0. If or 
defaulted, event flag 30 will be utilized for internal 
synchronization. If iefn is an event flag (1-96), the selected 
event flag is set as each buffer is filled. If iefn is greater 
than 96, it is considered to be a completion routine that will be 
called with a JSR PC. Such routines must return with an RTS PC 
(or a FORTRAN RETURN statement). Furthermore, FORTRAN completion 
routines must not do any I/O through the FORTRAN runtime system, 
since this may cause unpredictable results or fatal task errors. 

If multiple sweeps are initiated, the user should specify 
different event flags. Adherence to this limitation cannot be 
enforced by the software. 



Idelay 



The delay from the start event (STl) until the first sample in 
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ichn 

The number of the first channel to be sampled. The default of 
applies only if ichn was not established in a prior call to the 
SETADC routine. 



nchn 



The number of channels to sample. The default is 1. nchn may be 
set up with the SETADC routine. All nchn channels will be 
sampled on one clock interrupt. 



22.2.1.3 CLOCKA: Set Clock A Rate - The CLOCKA routine sets the rate 
for Clock A. The format of the call to this routine is as follows: 

CALL CLOCKA ( i rate , iprset , [ ind] , [lun] ) 

irate 

The clock rate. One of the following must be specified: 

Clock B overflow (not on Q-bus version) or no rate 

1 1 MHz 

2 100 KHz 

3 10 KHz 

4 1 KHz 

5 100 Hz 

6 Schmitt Trigger 1 

7 Line frequency 

iprset 

The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE routine can be 
used to calculate a clock preset value. 

ind 

Receives a success or failure code as follows: 

indicates illegal arguments. 

1 indicates Clock A set to start when sweep requested. 



lun 



The logical unit number. Present for LPA-11 compatibility. 
Ignored by K-series software. 
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22.2.1.4 CLOCKB: Control Clock B - The CLOCKS routine gives the user 
control over the KWll-K Clock B, which is used to maintain a 16-bit 
software clock. This feature is not available on LSI-11-bus versions. 
The 16-bit clock is incremented once per Clock B interrupt. The 
maximum value of the clock is 65535. 

The format of the call to CLOCKB is as follows: 

CALL CLOCKB ([ irate] ,[ iprset] , [mode] ,[ ind] , [lun] ) 



irate 



The clock rate. When irate is nonzero, the clock is set running 
at the selected rate after the preset value specified by iprset 
is loaded. The 16-bit software clock is not altered by starting 
the clock. The initial value of the 16-bit clock is when the 
program is loaded. 

When irate is 0, clock B is stopped but the 16-bit software clock 
is unaltered. 

When irate is defaulted, the 16-bit software clock is zeroed but 
clock B continues to run. 

The following are the acceptable values for irate: 

Stop Clock B 

1 IMHz 

2 100 KHz 

3 10 KHz 

4 1 KHz 

5 100 Hz 

6 Schmitt Trigger 3 

7 Line frequency 



iprset 



The count by which to divide clock rate to yield overflow rate. 
Overflow events can be used to maintain the 16-bit software clock 
and/or drive clock A. The default value is 1. The maximum 
practical overflow rate in interrupt mode is 10 KHz. The range 
of iprset is 1-255. The value in iprset can be established by 
use of the XRATE routine. 
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mode 

The options. Either of the following can be specified: 

indicates normal operations. This is the default. The 
16-bit software clock is updated on Clock B overflow. 
The overflow rate should not exceed lOKHz. The software 
does not check the overflow rate. 

1 indicates Clock B operates in noninterrupt mode. The 
16-bit clock is not incremented or altered. This allows 
a greater than lOKHz pulse to be sent to clock A. 



ind 



lun 



Receives a success or failure code as follows: 

indicates a failure to start Clock B. 

1 indicates Clock B started. 



The logical unit number. This argument is ignored by the 
K-series routines. It is present for LPA-11 compatibility. 



22.2.1.5 CVADF: Convert A/D Input to Floating Point - The CVADF 
routine converts an A/D input value to a floating-point number. The 
routine can be invoked as a subroutine or a function as follows: 

CALL CVADF (ival,val) 

or 

val = CVADF (Ival) 



ival 



A value obtained from A/D input. Bits 12-15 are the gain. Bits 
0-11 represent the value. 



val 

(REAL*4) receives the converted value. 
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22.2.1.6 DASWP; Initiate Synchronous D/A Sweep - The DASWP routine 
initiates synchronous D/A output to an AAll-K. 

The format of the DASWP call is as follows: 

CALL DASWP (ibuf ,lbuf , [nbuf] , [mode] , [iprset] , [iefn] , [Idelay] , 
[ichn] , [nchn] ) 



ibuf 



A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (lOSB) . 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 0. 



nbuf 



The number of buffers to be emptied. If nbuf is omitted or set 
equal to 0, indefinite emptying occurs. The STPSWP routine 
terminates indefinite emptying. 



mode 



The start criteria. Except where noted, the plus sign (+) 
preceding mode bit values listed below indicates that they are 
independent and can be added or ORed together. All bit values 
not listed below are reserved. 

The following values can be specified: 

indicates immediate start. This is the default. 

1 indicates that a group of data words, whose number is 
specified by nchn, is preceded by a scope control word 
(refer to Section 22.2.1.22 for a description of scope 
control words) . This bit setting is ignored if +512 is 
also specified. This feature is not included in the 
Q-bus (AAVll) version. 

The buffer size specified by Ibuf must be a multiple of 
nchn+1 words. The DASWP routine, however, does not 
enforce this restriction. 

2 sets the intensify bit after each pair of channels (nchn 
must be 2) have been output. This feature is supported 
on the Q-bus version only. It assumes that bit of 
DAC3 on the AAVll is connected to the intensify input on 
the oscilloscope. 

+256 indicates external start (STl) . 
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+512 indicates non-clock-overflow, non-interrupt-driven 
output (burst mode). This value cannot be specified 
with either external start (+256) or a nonzero Idelay 
value. A completion routine must be specified if nbuf 
is greater than the number of buffers supplied or if 
continuous burst output is desired. If nbuf equals -1, 
burst mode must be stopped by calling STPSWP from the 
completion routine. 



iprset 



The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 

— ^^« -^ '-"j.v,wj.wt-c a \^j.ijv^j\. (-•LcatSL VdJ-UG. 

If the iprset argument is omitted, the user must specify a mode 
value of +512. Otherwise, an error status code of 301 (invalid 
arguments) is returned into the lOSB. 



iefn 



An event flag number (from 1 to 96), or a completion routine, or 
0. If or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is emptied. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN statement). Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 

If multiple sweeps are initiated, the user should specify 
different event flags. This limitation cannot be enforced by the 
software. 

Idelay 

The delay from start event (STl) until the first sample in irate 
units. Default or indicates no delay. 

ichn 

The first channel number. The default is 0. 



nchn 



The number of channels. The default is 1. When nchn equals 2 
and mode does not contain +1, the size of data buffers specified 
in Ibuf must be an even number. The software does not check this 
requirement. 



22-15 



K-SERIES PERIPHERAL SUPPORT ROUTINES 

22.2.1.7 DIGO: Digital Start Event - The DIGO routine allows the user 
to specify the digital input bits that, when set, will cause the 
simulation of an external start event and the start of a pending 
sweep. 

The format of the call to DIGO is: 

CALL DIGO ( [iunit] , [mask] , [kount] ) 

iunit 

The DRll-K unit number. The default is 0. 



mask 



A logical mask that specifies one or more start bits. If zero, a 
pending digital start event request is immediately cancelled. If 
defaulted, an STl event is immediately simulated and the current 
value of the 16-bit software clock is returned in kount, if 
specified . 



kount 



Receives the current value of the 16-bit software clock when the 
defaulting of mask causes the simulation of an STl event. 



22.2.1.8 DINP: Digital Input - The DINP routine inputs a single 
16-bit word from a DRll-K. Bits read as a 1, can be masked with a 1, 
causing the clearing of the bit in the DRll-K input buffer. 

During the K-series routines generation dialog, it is possible to 
select one of two versions of the DINP routine: 

1. A slow version containing all functions described below 

2. A fast version that omits the functions provided by the mask, 
iosb, and input arguments 

The fast version of DINP can be invoked as a function (IDINP) only. 
The slow version of DINP can be invoked as a subroutine or a function. 
The formats of the invocations are as follows: 

CALL DINP ( [iunit] , [mask] , iosb, input) 

or 

ind=IDINP(iunit, [mask] ,iosb, [input] ) 



iunit 



The DRll-K unit number. This argument is required for the fast 
version of DINP. For the slow version, the default is 0. 
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mask 

The bit mask used to specify which input bits will be cleared in 
the digital input register. The default is 177777(8) indicating 
all bits will be cleared. 

iosb 

A 2-word I/O status block array (see Section 22.2.3). 

input 

Receives the data input from the DRll-K. 



ind 



Receives the data input from the DRll-K if DINP is invoked as a 
function. 



22.2.1.9 DISWP: Initiate Synchronous Digital Input Sweep - The DISWP 
routine initiates a synchronous digital input sweep through a DRll-K. 

The format of the call to DISWP is: 

CALL DISWP (ibuf ,lbuf , [nbuf ] , [mode] , [iprset] , [iefn] , [Idelay] , 
[iunit] ) 



ibuf 



A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB) . 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 0. 

nbuf 

The number of buffers to be filled. If nbuf is or defaulted, 
indefinite sampling occurs. The STPSWP routine is used to 
terminate indefinite sampling. 

mode The sampling options. The default is 0. The plus signs (+) 
preceding the mode bit values listed below indicate that they are 
independent and can be added or ORed together. 
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The following values can be specified: 

Single-word sample, immediate start. This is the 
default mode. 

+256 External start (STl) . 

+512 Nonclock overflow interrupt-driven input. External 
start and delay are illegal. 

+1024 Time-stamped sampling. The double word consists of one 
data word followed by the value of the 16-bit software 
clock at the time of the sample. This option is not 
available if the KWll-K clock is not being used (for 
example, on the Q-bus) . 



iprset 



The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 
be used to calculate a clock preset value. 

If the iprset argument is omitted, the user must specify a mode 
value of +512. Otherwise, an error status code of 301 (invalid 
arguments) is returned into the lOSB. 



iefn 



An event flag number (from 1 to 96), or a completion routine, or 
0. If or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is filled. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN statement). Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 

If multiple sweeps are initiated, the user shold specify 
different event flags. This limitation cannot be enforced by the 
software. 



Idelay 



The delay from start event (STl) until the first sample in irate 
units. Default or indicates no delay. 



lunit 

The DRll-K unit number. The default is 0. 
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22.2.1.10 DOSWP: Initiate Synchronous Digital Output Sweep - The 
DOSWP routine initiates a synchronous digital output sweep through a 
DRll-K. 

The format of the call to DOSWP is as follows: 

CALL DOSWP (ibuf ,lbuf ,[nbuf] , [mode] , [iprset] ,[iefn] , [Idelay] , 
[iunit] ) 



ibuf 



A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (lOSB) . 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size, and Ibuf must be greater than 0. 



nbuf 



The number of buffers to be emptied. If nbuf is or defaulted, 
indefinite emptying occurs. The STPSWP routine is used to 
terminate indefinite emptying. 

mode 

The start criteria. The default is 0. 

The following values can be specified in the high-order byte of 

mode : 

Immediate start. This is the default. 

+256 External event start (STl) . 

+512 Nonclock overflow, interrupt-driven output. External 
start and delay are illegal. 



iprset 



The clock preset. The clock rate divided by the clock preset 
value yields the clock overflow rate. The XRATE subroutine can 
be used to calculate a clock preset value. 

If the iprset argument is omitted, the user must specify a mode 
value of +512. Otherwise, an error status code of 301 (invalid 
arguments) is returned into the lOSB. 
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iefn 



An event flag number (from 1 to 96), or a completion routine, or 
0. If or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is emptied. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN statement) . Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 

If multiple sweeps are initiated, the user should specify 
different event flags. This limitation cannot be enforced by the 
software. 



Idelay 



The delay from start event (STl) until the first sample in irate 
units. Default or indicates no delay. 



iunit 

The DRll-K unit number. The default is 0. 



22.2.1.11 DOUT: Digital Output - The DOUT routine outputs a single 
16-bit word to a DRll-K. Only those bits in the output word specified 
by corresponding ones in a mask field are altered. 

During the K-series routines generation dialog, it is possible to 
select one of two versions of the DOUT routine: 

1. A slow version containing all functions described below 

2. A fast version that omits the functions provided by the mask 
and iosb arguments 

The slow version of DOUT can be invoked as a subroutine or a function. 
The fast version of DOUT can be invoked as a subroutine only. The 
formats of the invocations are as follows: 

CALL DOUT ( [iunit] , [mask] , iosb, idata) 

or 

iout=IDOUT( [iunit] , [mask] , iosb, idata) 

iunit 

The DRll-K unit number. The default is 0. 



mask 



Used to select which bits can be altered. The default is 
177777(8), indicating all bits. 
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iosb 

A 2-word I/O status block (see Section 22.2.3). 

idata 

The 16-bit output value for the DRll-K. A 1 sets a corresponding 
bit. A clears the corresponding bit. 



lout 



Receives a copy of the DRll-K output register after it has been 
altered . 



22.2.1.12 FLT16: Convert Unsigned Integer to a Real Constant - The 
FLT16 routine converts an unsigned 16-bit integer to a real constant 
(REAL*4) . It can be invoked as a subroutine or a function as follows: 

CALL FLT16 (ival,val) 

or 

val=FLT16 (ival [ ,val] ) 

ival 

An unsigned 16-bit integer. 

val 

The converted (REAL*4) value. 



22.2.1.13 GTHIST: Gather Interevent Time Data - The GTHIST routine 
initiates sampling to measure the elapsed time between events. The 
value of the Clock A buffer/preset register at the time of ST2 firing 
is stored in a user-provided buffer. 

GTHIST is an optional facility that must be explicitly selected during 
the K-series generation dialog prior to its use in any program. The 
format of the call to GTHIST is as follows: 

CALL GTHIST (ibuf ,lbuf , [nbuf] , [mode] , [iprset] , [iefn] , [kount] ) 

ibuf 

A 40-word array initialized by the SETIBF routine. The first two 
words of the array are the I/O status block (IOSB) . 



Ibuf 



The size in words of each data buffer. All data buffers must be 
equal in size and Ibuf must be greater than 0. 
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nbuf 

The number of buffers to be filled. If nbuf is or defaulted, 
indefinite sampling occurs. The STPSWP routine is used to 
terminate indefinite sampling. 

mode 

The sampling options as follows: 

indicates external event timing without Zero Base. This 
is the default. 

1 indicates external event timing with Zero Base. This is 
the only mode supported for the KWVll. 



iprset 



A null argument. It is present only to maintain compatibility 
with other sweep routine calling sequences. 

iefn 

An event flag number (from 1 to 96), or a completion routine, or 
0. If or defaulted, event flag 30 is used for internal 
synchronization. If iefn is an event flag from 1 to 96, the 
selected event flag is set as each buffer is filled. If iefn is 
greater than 96, it is considered a completion routine that will 
be called with a JSR PC. Such routines must return with an RTS 
PC instruction (or a FORTRAN RETURN statement). Furthermore, 
FORTRAN completion routines must not perform I/O through the 
FORTRAN run-time system since this may cause unpredictable 
results or fatal task errors. 

If multiple sweeps are initiated, the user should specify 
different event flags. This limitation cannot be enforced by the 
software. 

kount 

A counter used by GTHIST, as described below. 

To take Post-Stimulus Time data, set mode to 0. STl signals the 
occurrence of a stimulus and starts the clock (that is, no data is 
taken until the first STl occurs) . Each response is signalled by ST2, 
and the buffer/preset register contents are placed in the user buffer. 
Each STl resets the counter register to 0, and increments kount by 1. 
Thus, kount keeps track of the number of stimuli (STl events). Clock 
overflow stops the clock. The clock waits for the next STl event 
before restarting. The maximum stimulus-response interval is a 
function of the clock rate. 

To obtain Inter-Stimulus-Interval data, set mode to 1. The time 
between successive events, as signalled by ST2, is recorded. The 
maximum interevent tim.e is a function of the clock rate. When clock 
overflow occurs, the value returned on the next ST2 firing is 
177777(8) and KOUNT is incremented. Thus,- kount represents the number 
of times the maximum interevent time was exceeded. In general, the 
user should ignore values of 177777(8). 
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22.2.1.14 IBFSTS: Get Buffer Status - The IBFSTS routine returns 
information on buffers being used in a sweep. 

The format of the call to IBFSTS is as follows: 

CALL IBFSTS (ibuf,istat) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 



istat 



An array with as many elements as there are buffers involved in 
the sweep. The maximum is 8. IBFSTS fills each element in the 
array with the status of the corresponding buffer. The possible 
status codes aire as follows: 

+2 indicates that the buffer is in the device queue. That 
is, it is waiting to be filled or emptied. 

+1 indicates that the buffer is in the user queue. That 
is, it is full of data (for input sweeps) or is waiting 
to be filled (for output sweeps) . 

indicates that the status of the buffer is unknown. 
That is, it is not the current buffer nor is it in 
either the device or the user queue. 

-1 indicates that a service routine is currently using the 
buffer. 



22.2.1.15 ICLOKB: Read 16-bit Clock - The ICLOKB function returns the 
contents of the 16-bit software clock as an integer value to the user. 

The format of the ICLOKB function call is as follows: 

itim=ICLOKB(0) 



itim 



Receives the curent value of the 16-bit software clock as an 
unsigned integer. 



NOTE 

MACRO-11 programmers need not establish 
an argument block for the ICLOKB 
function. The current value of the 
software clock is returned in RO. 
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22.2.1.16 IGTBUF: Return Buffer Number - The IGTBUF routine returns 
the number of the next buffer to use. This routine should be called 
by user completion routines to determine the next buffer to access. 
It should not be used if an event flag was specified in the 
sweep-initiating call. Rather, the IWTBUF routine should be used with 
event flags. 

IGTBUF can be invoked as a subroutine or a function. The formats of 
the invocations are: 

CALL IGTBUF ( ibuf , ibuf no) 

or 

ibuf no=IGTBUF (ibuf [ , ibuf no] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 



ibufno 



Receives the number of the next buffer to access. If there is no 
buffer in the queue, ibufno contains -1. 



22.2.1.17 INXTBF: Set Next Buffer - The INXTBF routine alters the 
normal buffer selection algorithm. It allows the user to specify the 
number of the next buffer to be filled or emptied. 

INXTBF can be invoked as a subroutine or a function. The formats of 
the invocations are: 

CALL INXTBF ( ibuf , ibuf no [, ind] ) 

or 

ind=INXTBF (ibuf, ibuf no [, ind] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 



ibufno 



ind 



The number of the next buffer the user wants filled or emptied, 
The buffer must already be in the device queue. 



Receives an indication of the result of the operation: 

indicates that the specified buffer was already active 
or was not in the device queue. 

1 indicates that the next buffer was successfully set. 
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22.2.1.18 IWTBUF: Wait for Buffer - The IWTBUF routine allows a user 
task to wait for the next buffer to fill or empty. It should be used 
in conjunction with the specification of an event flag in the 
sweep-initiating call. This routine should not be used if a 
completion routine was specified in the call to initiate a sweep. 
Rather, the IGTBUF routine should be used with completion routines. 

IWTBUF can be invoked as a subroutine or a function. The formats of 
the invocations are as follows: 

CALL IWTBUF { ibuf , [ ief n] , ibuf no) 

or 

ibufno=IWTBUF(ibuf , [iefn] , [ibuf no] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 



iefn 



The event flag on which the task will wait. This should be the 
same event flag as that specified in the sweep-initiating call. 
If iefn equals or is defaulted, event flag 30 is used. 



ibufno 



Receives the number of the next buffer to be filled or emptied by 
the user's task. 



22.2.1.19 RCLOKB: Read 16-bit Clock - The RCLOKB routine returns to 
the user's task the contents of the 16-bit software clock as a real 
constant. 

RCLOKB can be invoked as a subroutine or a function as follows: 

CALL RCLOKB (rlast,time) 
or 

time=RCLOKB(rlast,time) 



time 



Receives the current value of the 16-bit software clock as a real 
constant (REAL*4) . 



rlast 



A value (REAL*4) to be subtracted from the current 16-bit 
software clock before it is returned into the time field. 
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22.2.1.20 RLSBUF: Release Data Buffer - The RLSBUF routine declares 
one or more buffers free for use by the interrupt service routine. 

The RLSBUF routine must be called to release buffer (s) to the device 
queue before the sweep is initiated. The device queue must always 
contain at least one buffer to maintain continuous sampling. 
Otherwise, buffer overrun occurs (see Section 22.3 for a discussion of 
buffer management) . Note that RLSBUF does not verify whether the 
specified buffers are already in a queue. 

The format of the call to RLSBUF is as follows: 

CALL RLSBUF ( ibuf , ind ,nO [ ,nl . . . ,n7] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 

ind 

Receives a success or failure code as follows: 

indicates illegal buffer number specified. 

1 indicates buffer(s) successfully released. 

nO,nl,and so forth 

The numbers of buffers to be released. A maximum of eight can be 
specified. 



22.2.1.21 RMVBUF: Remove Buffer from Device Queue - The RMVBUF 
routine removes a buffer from the device queue. 

The format of the call to RMVBUF is as follows: 

CALL RMVBUF ( ibuf ,n [, ind] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 

n 

The number of the buffer to remove. 

ind 

Receives a success or failure code as follows: 

indicates that the specified buffer was not in the 
device queue. 

1 indicates that the specified buffer was removed from the 
queue . 
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22.2.1.23 SETADC: Set Channel Information - The SETADC routine 
establishes channel start and increment information for an A/D sweep. 

SETADC can be invoked as a subroutine or a function as follows: 
CALL SETADC ( ibuf , [ i f lag] , [ ichn] , [nchn] , [ inc] , [ ind] ) 

or 

ind = ISTADC(ibuf, [iflag] , [ichn] , [nchn] , [inc] , [ind] ) 

ibuf 

A 40-word array initialized by the SETIBF routine. 



iflag 



Equals zero if the user wants absolute addressing and nonzero for 
programmable gain addressing. The default is 0. 



ichn 

The first channel number. The default is 0. 



nchn 



The number of samples to be taken per interrupt. The default is 

1. 



inc 



The channel increment. The default is 1. The user should 
specify an increment of 2 for differential A/D input. 

ind 

Receives a success or failure code as follows: 

indicates an illegal channel number. 

1 indicates successful recording of channel information 
for an A/D sweep. 

22.2.1,24 SETIBF: Set Array for Buffered Sweep - The SETIBF routine 
initializes an array required by buffered sweep routines. 

The format of the call to SETIBF is as follows: 

CALL SETIBF { ibuf , [ ind] , [ lamskb] ,buf [ ,buf 1 . . .buf 7] ) 

ibuf 

A 40-word array. 
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Receives a success or failure code as follows: 



indicates an illegal number of buffers was specified. 
SETIBF initializes the array according to the maximum 
number of buffers allowed. This maximum number of 
buffers is specified by the user during the K-series 
generation dialog. 

1 indicates the array was successfully initialized. 



lamskb 



Present for compatibility with LPA-11 routines. It is ignored by 
K-series software. 

bufO, etc. 

The name of a buffer. A maximum of eight buffers can be 
specified. Any buffer names in excess of eight are ignored. At 
least two buffers must be specified to maintain continuous 
sampling . 

Each buffer specified in the call to SETIBF is assigned a number from 
to 7. 

The assignment of these numbers is based on the order in which buffer 
names appear in the argument list. The first buffer whose name 
appears in the list is assigned number 0, the second is assigned 
number 1, and so forth. In all subsequent calls to other K-series 
routines involving the set of buffers specified in a call to SETIBF, 
these numbers, rather than names, are used to refer to particular 
buffers. 



22.2.1.25 STPSWP: Stop Sweep - The STPSWP routine allows the user to 
stop a sweep that is in progress. 

The format of the call to STPSWP is as follows: 

CALL STPSWP (ibuf [,iwhen] , [ind] ) 

ibuf 

The 40-word array specified in the call that initiated a sweep. 

iwhen 

Specifies when to stop the sweep: 

indicates at the next sample. This is the default. 

+n (any positive value) indicates at the end of the current 
buffer. 

-n (any negative value) is reserved. 
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ind 

Receives a success or failure code as follows: 

indicates that the sweep was not active or no sweep 
could be found that was associated with the specified 
ibuf . 

1 indicates that the sweep will be stopped (at the time 
indicated by iwhen) . 



22.2,1.26 XRATE: Compute Clock Rate and Preset - The XRATE routine 
computes an appropriate clock rate and preset that will achieve a 
desired dwell (intersample interval). 

NOTE 

The XRATE routine can be used only on 
systems that have a FORTRAN or 
BASIC-PLUS-2 compiler. 

XRATE can be invoked as a subroutine or a function as follows: 

CALL XRATE (dwell , i rate , iprset , i flag) 
or 

adwell = XRATE(dwell , irate, iprset ,iflag) 

dwell 



The intersample time desired by the user. The time is expressed 
in decimal seconds (REAL*4) . 



irate 

Receives the computed clock rate as a value from 1 to 5. 



iprset 

Receives the clock preset. 



iflag 



Specifies whether the computation is intended for Clock A or 
Clock B: 

indicates the computation is for Clock A. 

nonzero indicates the computation is for Clock B. 



The actual dwell rate for the clock based on the irate and iprset 
parameters . 
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CALL 


ksubr 


.PSECT 


data 


.BYTE 


narg ,0 
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22.2.2 MACRO-11 Interface 

MACRO-11 programmers access the K-series support routines described in 
Section 22.2.1 through either of two techniques: 

1. The standard subroutine linkage mechanism and the CALL op 

code 

2. Special-purpose macros that generate an argument list and 
invoke a subroutine 

These techniques are described in the following subsections. 



22.2.2.1 Standard Subroutine Linkage and CALL Op Code - K-series 

routines can be accessed through use of the standard subroutine 

linkage mechanism and the CALL op code. The format of this procedure 
is: 

.PSECT code 

; ARGUMENT ADDRESS TO R5 
;CALL K-SERIES ROUTINE 

arglist: .BYTE narg,0 ;NUMBER OF ARGUMENTS 

.WORD addrl ;FIRST ARGUMENT ADDRESS 



.WORD addrn ;LAST ARGUMENT ADDRESS 

In this sample, the two PSECT directives are shown only to indicate 
the noncontiguity of the code and data portions of the linkage 
mechanism. Within the argument list, any argument that is to be 
defaulted must be represented by a -1 (that is, 177777(8)). 



22.2.2.2 Special-Purpose Macros - To facilitate the calling of 
K-series support routines from a MACRO-11 program, two macros are 
provided in file [45, 10] LABMAC.MAC. These macros are: 

1. INITS 

2. CALLS 

INITS is an initialization macro. It should be invoked at the 
beginning of the MACRO-11 source module. 

CALLS invokes a K-series support routine. The format of this macro 
call is as follows: 

CALLS ksubr, ARGl,. . .,ARGN> 

ksubr 

The name of a K-series support routine. 

argl,etc. 

Arguments to be formatted into an argument list and passed to the 

-..-w- j^w<«^ii « 1. sj ^*iiis-** I- ^^a^x Kf^ ^j.uijcL a o y iLiiji^ J, J. u name ur a 

constant (interpreted as a positive decimal number) or can be 
defaulted. 
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22.2.3 The I/O Status Block (lOSB) 

Each active sweep must have its own I/O status block. The I/O status 
block (lOSB) is a 2-word array allocated in the user's program. It is 
used to receive the status of a call to a K-series support routine. 
When a data sweep routine is called, the lOSB is always the first two 
words of the 40-word array specified as the first argument of the 
call. The first word of the lOSB contains the status code. The 
second word contains the buffer size in words. 

The codes that can appear in the first word of an I/O status block are 
in ISA-compatible format (with the exception of the I/O pending 
condition) . Table 22-3 lists all return codes. 



Table 22-3 
Contents of First Word of lOSB 



lOSB word 1 





1 
301 
305 
306 
313 
315 
317 
397 



Meaning 



Operation pending; I/O in progress 

Successful completion 

Invalid arguments 

Hardware or software option not present 

Illegal buffer specification 

Data overrun 

Request terminated 

Resource in use 

Invalid event flag 



22.3 BUFFER MANAGEMENT 

The management of buffers for data sweeps by K-series support routines 
involves the use of two FIFO (First-In, First-Out) queues: 

1. The device queue (DVQ) 

2. The user queue (USQ) 

The device queue (DVQ) contains the numbers of all buffers that the 
user has released to the support routines in a call to RLSBUF. The 
buffers represented by these numbers are ready to be filled with data 
(input sweeps) or to be emptied of data (output sweeps). Any buffer 
specified in a call to INXTBF must already be in DVQ. 
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The user queue (USQ) contains the numbers of buffers available to the 
user. For output sweeps, this queue contains the numbers of buffers 
that have already been emptied by the driver. For input sweeps, the 
buffers represented by USQ are those which are filled with data. In 
both instances, the user's task determines the next buffer to use 
(that is, extracts the first element of USQ) by callinq IGTBUF or 
IWTBUF, 

Both the DVQ and USQ are initialized to -1, indicating no buffers, 
when the user's task calls the SETIBF routine. The task must call 
RLSBUF before initiating any sweep, since at least one buffer must be 
present in DVQ for the first input or output to occur. 

For input sweeps, the best strategy is to call RLSBUF, specifying the 
numbers associated with all the buffers to be used in the sweep. 

For output sweeps, one approach is to specify two buffers (for 
continuous sweeps) in the call to RLSBUF. The first action then taken 
either in a completion routine or after a call to IWTBUF would be to 
release the next buffer. Note, however, that this approach does not 
represent true multiple buffering, since data overrun occurs if the 
second buffer is not released in time. 



22.4 SAMPLE FORTRAN PROGRAMS 

Two sample FORTRAN programs showing the use of K-series support 
routines are presented in this section. The first program uses event 
flags for internal synchronization. The second program demonstrates 
the use of user-supplied completion routine for synchronization. 

NOTE 

FORTRAN completion routines must not 
contain any of the following: 

• Any I/O through the FORTRAN run-time 
system 

• Any use of virtual arrays 

• Any use of floating-point operations 



• 



Any errors, since error reporting is 
done through the FORTRAN run-time 
system 

Anything else that may change the 
FORTRAN impure area 



Any of the above may result in fatal task errors or unpredictable 
results. 
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22.4.1 Sample Program Using Event Flag 

IMPLICIT INTEGER (A-Z) 

DIMENSION BUF(1024,8), IBUF (40), I0SB(2) 
EQUIVALENCE (IBUF ( 1 ) , lOSB { 1 ) ) 

C 

C INITIALIZE THE IBUF ARRAY FOR THE A/D SWEEP 

C 

CALL SETIBF (IBUF,IND, , BUF(1,1), BUF(1,2), BUF(1,3), 

* BUF(1,4), BUF(1,5), BUF(1,6), BUF(1,7), BUF(1,8)) 

WRITE (1, 900) 

READ (1, 910) IRATE, IPRSET 
C 
C SET THE CLOCK RATE AND PRESET FOR THE SWEEP 

C 

CALL CLOCKA (IRATE, IPRSET, IND) 

C 

C THIS IS INPUT, SO RELEASE ALL BUFFERS TO SERVICE 

C ROUTINE 

C 

CALL RLSBUF (IBUF, IND, 0,1,2,3,4,5,6,7) 

C 

C START THE SWEEP. USE 1024 WORD BUFFERS, SAMPLE 

C FOREVER, EXTERNAL START, EVENT FLAG 30, 1 CHANNEL (0) 

C 

CALL ADSWP (IBUF, 1024, -1, 256, IPRSET, 

* 30, 0, 0, 1) 

C 

C HERE WE COULD CHECK THE I/O STATUS BLOCK TO ENSURE 

C THAT THE SWEEP IS ACTUALLY RUNNING. 

C 

IBFCNT=0 
C 

C THIS IS THE TOP OF THE DATA PROCESSING LOOP. WE 

C WAIT FOR A BUFFER TO BE COMPLETED, AND THEN DUMP 

C THE FIRST 100 WORDS OF THE BUFFER TO LUN 1. 

C 

10 IBUFNO = IWTBUF(IBUF, 30)+l 
C 

C IWTBUF WILL RETURN A POSITIVE BUFFER NUMBER 

C AS LONG AS THERE IS A BUFFER OF DATA AVAILABLE. 

C IF IND IS -1, WE PROBABLY HAD DATA OVERRUN, SO STOP. 

C 

IF (IBUFNO .EQ. 0) STOP 

IBFCNT=IBFCNT+1 

WRITE (1,920) IBFCNT 

WRITE (1,930) (BUF(I, IBUFNO) , 1=1,100) 
C 
C RELEASE BUFFER FOR SERVICE ROUTINE TO REFILL 

C 

CALL RLSBUF(IBUF,IND,IBUFN0-1) 

GOTO 10 
900 FORMAT (' ENTER IRATE, IPRSET:', $) 
910 FORMAT (I, 0) 

920 FORMAT (' DUMP OF BUFFER NUMBER ',15,/) 
930 FORMAT (IX, 1007) 

END 
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22.4.2 Sample Program Using Completion Routine 

IMPLICIT INTEGER {A-Z) 
EXTERNAL AST 

DIMENSION BUF(1024, 8) , IBUF (40), I0SB(2) 
COMMON /KDATA/ BUF, IBUF, IBFCNT 
EQUIVALENCE ( IBUF (1 ) , lOSB (1) ) 

C 

C INITIALIZE THE IBUF ARRAY FOR THE A/D SWEEP 

C 

CALL SETIBF (IBUF,IND, , BUF(1,1), BUF(1,2), BUF(1,3), 

* BUF(1,4), BUF(1,5), BUF(1,6), BUF(1,7), BUF(1,8)) 

WRITE (1, 900) 
READ (1, 910) IRATE, IPRSET 
C 

C SET THE CLOCK RATE AND PRESET FOR THE SWEEP 

C 

CALL CLOCKA (IRATE, IPRSET, IND) 
C 

C THIS IS INPUT, SO RELEASE ALL BUFFERS TO SERVICE 

C ROUTINE 

C 

CALL RLSBUF (IBUF, IND, 0, 1, 2, 3, 4, 5, 6, 7) 
C 

C START THE SWEEP. USE 1024 WORD BUFFERS, SAMPLE 

C FOREVER, EXTERNAL START, EVENT FLAG 30, 1 CHANNEL 

(0). 
C 

IBFCNT = 

CALL ADSWP (IBUF, 1024, 0, 256, IPRSET 

* AST, 0, 0, 1) 

C 

C ■ HERE WE COULD CHECK THE I/O STATUS BLOCK TO ENSURE 

C THAT THE SWEEP IS ACTUALLY RUNNING. 

C 

10 CALL WAITER (23) 
C 

C WHEN EVENT FLAG 23 IS SET THE SWEEP IS COMPLETED. 

C WE MAY EXIT NOW. 

C 

STOP 

900 FORMAT (' ENTER IRATE, IPRSET:', $) 
910 FORMAT (I, 0) 

END 

SUBROUTINE AST 
C 

C THIS SUBROUTINE IS CALLED AT AST LEVEL WHENEVER 

C A BUFFER IS COMPLETED. THIS ROUTINE PROCESSES 

C THE CONTENTS OF THE BUFFER AND THEN RELEASES 

C IT FOR THE SERVICE ROUTINE. IF THE SWEEP IS TO 

C TERMINATE (lOSB NON-ZERO) THEN EVENT FLAG 23. IS 

C SET TO INDICATE TO THE MAINLINE CODE THAT WE ARE 

C DONE. 

IMPLICIT INTEGER (A-Z) 

DIMENSION BUF(1024, 8) , IBUF(40), I0SB(2) 

COMMON /KDATA/ BUF, IBUF, IBFCNT 

EQUIVALENCE ( IBUF (1 ) , lOSB ( 1 ) ) 

IBUFNO = IGTBUF (IBUF) +1 
IF (IBUFNO-1) .GE. GOTO 20 
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IF (lOSB(l) .EQ. 0) PAUSE 'INCONSISTENT STATE' 

CALL SETEF (23) 

RETURN 

20 IBFCNT = IBFCNT + 1 

C 

C HERE WE WOULD PROCESS THE DATA 

C 

C 

C RELEASE BUFFER FOR SERVICE ROUTINE 

C 

CALL RLSBUF (IBUF, IND, IBUFNO-1) 
RETURN 

END 
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22.2.1.22 SCOPE: Control Scope - The SCOPE routine allows the user to 
control the status register of an AAll-K. 

The format of the call to SCOPE is as follows: 

CALL SCOPE (iunit,icntrl,iosb) 



iunit 



The AAll-K unit number. 



icntrl 



A combination of bit values as shown in Table 22-2. Any bits not 
listed in this table are cleared before output to the AAll-K 
status register 



iosb 



A 2-word I/O status block (see Section 22.2.3). 



Table 22-2 
Scope Control Word Values 



Decimal Value 


Octal Value 


Function 


4096 


10000 


Erase storage CRT 




2048 


4000 


Set write-through mode 




1024 


2000 


Set store mode 




512 


1000 


A digital signal available 
the AAll-K. 


in 


12 


14 


Intensify on X or Y 




8 


10 


Intensify on Y 




4 


4 


Intensify on X 




2 


2 


Fast intensify enable 




1 


1 


Intensify pulse 





The values in Table 22-2 are also used to create scope control words 
for calls to the DASWP routine with a mode value of 1. 



22-27 



CHAPTER 23 
UNIBUS SWITCH DRIVER 



23,1 INTRODUCTION 

The UNIBUS switch driver supports DT07 UNIBUS switch hardware on 
RSX-llM-PLUS systems. UNIBUS switches are electronic devices that 
allow peripherals to be switched from one CPU to another, enabling 
CPUs_ to share peripheral devices. UNIBUS switches also facilitate 
on-line system backup and allow dynamic reconfiguration of systems in 
which high availability of certain peripherals is required. 



23.1.1 DT07 UNIBUS Switches 

DT07 UNIBUS switches can provide two, three, or four ports for 
connecting an external UNIBUS run to one of two, three, or four CPUs. 

Any CPU can request connection to a UNIBUS run and receive the 
connection immediately if the requested UNIBUS run is in the neutral 
state (it is not connected to another CPU's UNIBUS). If the request 
is received when the UNIBUS run is connected to another CPU, an 
interrupt is generated, informing the connected CPU of the pending 
request, and a watchdog timer is started. The connected CPU normally 
acknowledges the request, indicating the UNIBUS is still in use. In 
this case, the UNIBUS remains connected to the CPU. However, if the 
CPU does not respond to the interrupt within the time limit imposed by 
the DT07's watchdog timer, the UNIBUS is switched to the requesting 
CPU. Thus, a CPU that is not operating remains connected to the 
UNIBUS only until another CPU requests the UNIBUS. 

Each DT07 UNIBUS switch port functions as an isolation circuit. When 
its power is off, it does not affect any CPU operation. 



23.1.2 UNIBUS Switch Driver 

The UNIBUS switch driver permits the UNIBUS switch to be used in one 
of two ways: 

1. A CPU retains the UNIBUS until the task issuing the 
directives that connected the UNIBUS to this CPU exits. This 
is normally accomplished when the task attaches the UNIBUS 
switch (10. ATT function) and issues the connect function 
(10. CON). When the task exits (for any reason), the system 
detaches the UNIBUS switch (lO.DET) and performs an implicit 
disconnect function (lO.DIS) , releasing the UNIBUS switch for 
use by any other task. 
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The task that attaches the UNIBUS switch can be considered 
the manager of the UNIBUS switch until the task exits. The 
task can receive ASTs for certain conditions involving UNIBUS 
switching (see Section 23,3.1.1). 



A CPU retains the UNIBUS until 
explicitly disconnects the 
accomplished when a task issues 
previous 10. ATT was issued, 
the task exits. The UNIBUS th 
either the CPU fails to respond 
UNIBUS, or a task is executed th 
UNIBUS. Note that when operat 
task is required in order to ret 



a task is executed that 
UNIBUS. This is normally 
the 10. CON function and no 
Once the UNIBUS is connected, 
en remains connected until 
to other CPU requests for the 
at explicitly disconnects the 
ing in this manner, no active 
ain the UNIBUS. 



23.2 GET LUN INFORMATION MACRO 

Word 2 of the buffer filled by the Get LUN Information system 
directive (the first characteristics word) contains all Os. Words 3, 
4, and 5 are undefined. 



23.3 QIO MACRO 

This section summarizes standard and device-specific QIO functions for 
UNIBUS switches. 



23.3.1 Standard QIO Functions 

Table 23-1 lists the standard functions of the QIO macro that are 
valid for UNIBUS switches. 



Table 23-1 
Standard QIO Functions for UNIBUS Switches 



Format 


Function 


QIO$C lO.ATT, ... ,<[ast] > 
QIO$C lO.DET,... 
QIO$C lO.KIL,... 


ATTACH device 
Detach device 
Cancel I/O requests 



ast 

The address of an optional AST routine which will be entered if 
certain conditions are detected (see Section 23.3.1.1) 

10. ATT does not connect the UNIBUS switch (see device-specific 
function 10. CON) . 

-r^ T^T-im .T_j 1_ Jul TTVT1-I T»r» „t«^J U f^ — . J-U» 4 ..-.1, T4^ 4-V»i-. ITMTD TTC C?T.TT-f-r^V> 

was previously attached by the 10. CON function, an implied disconnect 
(lO.DIS) function is performed. 
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The only I/O requests that can be affected by the lO.KIL function are 
10. CON and 10. DPT. When lO.KIL Is issued during an 10. CON function, 
further retries are canceled. When lO.KIL is issued during an 10. DPT 
function, the time-out count is changed, forcing time-out (lE.TMO) to 
occur , 



23.3.1.1 10. ATT - The 10. ATT QIO function attaches the UNIBUS switch 
to the task issuing the QIO directive. An optional AST address 
parameter can be specified. However, if it is specified, it must 
remain valid while the UNIBUS switch remains attached to the task. 

The AST service routine for the UNIBUS switch is entered when one of 
the following conditions occur: 

• The UNIBUS switch has become connected to another CPU because: 

1. The operator manually switched the UNIBUS to another CPU, 
or 

2. This CPU failed to respond to another CPU's request for 
the UNIBUS within the specified time (the CPU must 
acknowledge the request by servicing an interrupt, as 
described in Section 23.1.1). 

UNIBUS switch condition code 1 is passed to the AST routine by 
the stack, indicating the cause of the AST. 

• The UNIBUS switch has disconnected from the CPU because: 

1. A power failure occurred in this CPU (system power 
failure) and the UNIBUS switch driver was unable to 
reconnect the bus, or 

2. A power failure occurred on the connected UNIBUS, causing 
the driver to automatically disconnect the UNIBUS 

UNIBUS switch condition code 2 (for a system power failure) or 
condition code 3 (for a UNIBUS power failure) is passed to the 
AST routine by the stack indicating the cause of the AST. 



23.3.1.2 lO.DET - The lO.DET function detaches the issuing task from 
the UNIBUS switch, and in addition, performs an implied disconnect for 
the issuing task if that task had connected the UNIBUS switch. A 
detach function is generated by the Executive on behalf of an attached 
task if that task exits (normally'or abnormally) without explicitly 
detaching the device. For a switched UNIBUS, this causes it to be 
disconnected if an attached, connected task faults in such a way as to 
cause it to exit. 



23.3.1.3 lO.KIL - The lO.KIL function will cancel any outstanding 

10. CON function that has a nonzero retry count and any outstanding 

10. DPT function that has not yet timed out. Other QIO functions in 

progress are not affected by lO.KIL, and are automatically completed. 
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23.3.2 Device-Specific QIO Functions 

The device-specific functions of the QIO macro that are valid for 
UNIBUS switches are shown in Table 23-2. 



Table 23-2 
Device-Specific QIO Functions for UNIBUS Switches 



Format 


Function 


QIO$C lO.CON,. . .,<[rcnt] , [cpu]> 
QIO$C lO.DIS,. . . ,<[tout] , [port]> 
QIO$C 10. DPT,. ..,< [tout] , [port] > 

QI0$C lO.SWI, . .. ,<cpu> 

QIO$C lO.CSR,... 


Connect UNIBUS switch 

Disconnect UNIBUS switch 

Disconnect UNIBUS switch 
from specified CPU port 

Switch the UNIBUS from 
current CPU to specified CPU 

Read UNIBUS switch CSR 



rent 



cpu 



The number of additional times the connect will be attempted if 
the 10. CON fails to complete. 



The ASCII letter designating the CPU to receive the UNIBUS 
switch. 



port 



The port number, ranging from through 3, of the target CPU that 
must request the bus prior to the CPU that is currently connected 
to the UNIBUS actually completing the disconnect. The port 
number corresponds to the four MANUAL CONNECT switch positions 
(PORT through PORT 3) marked on the DT07 control panel. 



tout 



The maximum time (in seconds) allowed (253. maximum) for the 
function to be completed before an error condition is reported. 

Parameter details are included in the following sections. 



23.3.2.1 10. CON - The 10. CON (connect) function requests connection 
of a UNIBUS presently not connected to a specified CPU. It can be 
issued either by a task previously attached with the 10. ATT function 
or by a task that is not attached. The 10. CON function has four 
optional parameters. The use of each parameter is described as 
follows. 

Retry Count -- The retry count specifies the number of additional 
times the connect function will be attempted if the 10. CON fails to 
complete within the time-out period of the UNIBUS switch. Retry count 
parameters used in this manner are always nonzero positive values. 
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The 10. CON function is not completed until either the retry count 
expires or the UNIBUS switch is successfully connected. Thus, the 
issuing task having a nonzero retry count wil not be checkpointed 
until the 10. CON function is completed. 

When a retry count of is specified, the connect function attempts to 
connect the UNIBUS switch once (no retries) and immediately reports 
the directive status to the issuing task. 

When a retry count of 177777 (-1) is specified, the connect function 
continues to retry the connection until a successful connection is 
made or an lO.KIL function is issued. 

CPU — The CPU parameter can only be used with loosely coupled-'- 
multiprocessor systems to specify the CPU to which the UNIBUS switch 
should be connected. This function is used only when the UNIBUS 
switch is presently not connected (the lO.SWI function should be used 
to disconnect the UNIBUS switch from a connected closely coupled CPU 
and connect it to a specified closely coupled CPU) . The CPU is 
specified by a single ASCII letter (A, B, C, or D) . 



23.3.2.2 lO.DIS - The lO.DIS function is used to disconnect the 
switched UNIBUS from the currently connected CPU. 

NOTE 

It is the responsibility of the task 
issuing the lO.DIS or 10. DPT function to 
determine that all devices on the 
switched UNIBUS are inactive when the 
function is issued. The UNIBUS switch 
driver does not check for active devices 
on the UNIBUS before completing either 
the lO.DIS or 10. DPT function. 



23.3.2.3 10. DPT - The 10. DPT function is used in a loosely coupledl 
multiprocessor system to allow the UNIBUS to be connected to another 
CPU on a specified port if the CPU requests connection within a 
specified time interval. (Refer to the note at the end of Section 
23.3.2.2.) 

Time-out — The time-out parameter specifies the maximum time allowed 
for the function to complete before an error is reported. Time-out 
specifications are positive, nonzero values ranging from 1 to 254 
seconds. The default time-out value is 2 seconds. If the CPU 
parameter is included in the 10. DPT function, the driver waits for the 
specified CPU to request the UNIBUS up to the specified time-out 
value. If the CPU does not request the UNIBUS during this time, the 
UNIBUS remains connected and the lE.TMO status is returned to the 
issuing task. 



1. A loosely coupled system is one in which memory resources are not 
shared by more than one CPU. 
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If a time-out value of is specified, the lO.DIS function will not 
complete until either the successful disconnect occurs, or an lO.KIL 
function is issued. 

Port — The port parameter can only be used with loosely coupled 

multiprocessor systems to specify the port through which the UNIBUS 

switch should be connected to a CPU. The port is specified by a 
number ranging from through 3. 



23.3.2.4 lO.SWI - The lO.SWI function disconnects the UNIBUS switch 
from the currently connected CPU and connects it to the specified CPU 
in a closely coupled system. The CPU parameter is required. 

lO.SWI is executed without the possibility of a third CPU taking 
control of the UNIBUS during the switching process. 

The CPU parameter is used in closely coupled multiprocessor systems to 
specify the CPU to which the UNIBUS switch should be connected. The 
CPU Is specified by a single ASCII letter (A, B, C, or D) . 



23.3.2.5 lO.CSR - The lO.CSR function reads maintenance information 
contained in the device CSR and returns it in the second word of the 
I/O status block. Information returned is valid only if the UNIBUS 
switch is connected. The use of this function should be limited to 
diagnostic applications. 



23.4 POWER-FAIL RECOVERY 

23.4.1 System Power-Fail Recovery 

During power-fail recovery, the driver attempts to restore the state 
of the system prior to the actual power failure. If the UNIBUS switch 
is found to be disconnected during power-fail recovery, the driver 
attempts to reconnect the switched UNIBUS. If the first attempt to 
reconnect the UNIBUS is not successful, an entry is made in the error 
log and the attached task is notified of the UNIBUS switch state by 
the AST specified in the 10. ATT function (if previously issued) . 

If an 10. CON function was in progress when the power failure occurred 
and a retry count was pending, the UNIBUS switch driver attempts to 
successfully connect the UNIBUS switch until the retry count expires. 

If an lO.DIS or 10. DPT function was in progress when the power failure 
occurred, the UNIBUS switch driver attempts to complete the operation. 



23.4.2 UNIBUS Power-Fail Recovery 

If an interrupt is received from the UNIBUS switch indicating a power 
failure has occurred on the switched UNIBUS, the driver issues an 
immediate disconnect (lO.DIS) . The attached task (if any) is notified 
by the AST. Note that the system may be corrupted if some of the I/O 
devices on the switched UNIBUS were active when the power failure 
occurred, since the drivers for those I/O devices may attempt to 
access the device registers after the switched UNIBUS (and I/O 
devices) has become disconnected. 
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23.5 STATUS RETURNS 



Table 23-3 lists the error and status conditions that are returned by 
the UNIBUS switch driver. 



Table 23-3 
UNIBUS Switch Driver Status Returns 



Code 



IS. sue 



IS.PND 



IE. ABO 



IE. BAD 



IE. CNR 



lE.DAA 



lE.DNA 



lE.IFC 



Reason 



Successful completion 

The operation specified in the QIO directive was 
completed successfully. 

I/O request pending 

The operation specified in the QIO directive has not 
yet been executed. The I/O status block is filled 
with Os. 

Request aborted 

An I/O request was queued (not yet acted upon by the 
driver) when an lO.KIL was issued. 

Bad parameters 

The parameters specified in the QIO macro were in 
error. 

Connect rejected 

The connect function did not successfully connect the 
switched UNIBUS to the specified CPU, and the retry 
count, if specified, has expired. 

Device already attached 

The device specified in an 10. ATT funcion was already 
attached by the issuing task. This code indicates 
that the issuing task has already attached the 
desired physical device unit, not that the unit was 
attached by another task. 

Device not attached 

The physical device unit specified in an lO.DET 
function was not attached by the issuing task. This 
code has no bearing on the attachment status of other 
tasks. 

Illegal function 

A function code was specified in an I/O request that 
is illegal for the UNIBUS switch driver. 



(continued on next page) 
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Table 23-3 (Cont.) 
UNIBUS Switch Driver Status Returns 



Code 



IE. NOD 



lE.OFL 



lE.SPC 



lE.TMO 



Reason 



Insufficient buffer space 

Dynamic storage space has been depleted, resulting in 
insufficient buffer space available to allocate 
either the I/O packet or the device list buffer. 

Device off line 

The physical device unit associated with the LUN 
specified in the QIO directive (the UNIBUS switch) 
was not on line, or the CPU specified in the 10. CON 
or lO.SWI was not on line. 

Illegal address space 

The buffer specified in the 10. CON function was 
partially or totally outside the address space of the 
issuing task. 

Time-out error 

The time-out count expired during an 10. DPT operation 
before the target CPU requested the UNIBUS. This 
error code is also returned when the DT03/DT07 
hardware fails to respond to a request due to a 
hardware failure. 



23.6 FORTRAN USAGE 

All of the QIO functions described for the UNIBUS switch driver can be 
used in FORTRAN tasks, except AST support is not provided (10. ATT 
function with an AST address specified) . A macro subroutine can be 
written for the FORTRAN task to call that specifies the AST address. 
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APPENDIX A 
SUMMARY OF I/O FUNCTIONS 



This appendix summarizes legal I/O functions for all device drivers 
described in this manual. Both devices and functions are listed 
alphabetically. The meanings of the five parameters represented by 
the ellipsis (...) are described in Section 1,5.1. The meanings of 
the function-specific parameters shown below are discussed in the 
appropriate driver chapters. The user may reference these functions 
symbolically by invoking the system macros FILIO$ (standard I/O 
functions) and SPCIO$ (special I/O functions) , or by allowing them to 
be defined at task-build time from the system object library. 



A.l ANALOG-TO-DIGITAL CONVERTER DRIVERS 
lO.KIL,... Cancel I/O requests 

lO.RBC, . . . ,<stadd ,size,stcnta> INITIATE an A/D conversion 



A. 2 CARD READER DRIVER 

10. ATT,., 

lO.DET, 

lO.KIL, 

lO.RDB, . . . ,<stadd,size> 

lO.RLB, . . . ,<stadd,size> 

lO.RVB, . . . ,<stadd,size> 



Attach device 

Detach device 

Cancel I/O requests 

READ logical block (binary) 

READ logical block (alphanumeric) 

READ virtual block (alphanumeric) 



A. 3 CASSETTE DRIVER 

10. ATT, ., 

lO.DET, . 

10. EOF,. 

xO • K J- u f • 

lO.RLB,. 



,<stadd,size> 



Attach device 
Detach device 
Write end-of-file gap 
Cancel I/O requests 
READ logical block 
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lO.RVB, . 
lO.RWD, . 
lO.SPB, . 
lO.SPF, . 
lO.WLB, . 
lO.WVB, . 



,<stadd ,size> 

,<nbs> 
,<nes> 

,<stadd ,size> 
,<stadd,size> 



READ virtual block 
Rewind tape 
SPACE blocks 
SPACE files 
WRITE logical block 
WRITE virtual block 



A. 4 COMMUNICATION DRIVERS (MESSAGE-ORIENTED) 



10. ATT,. 
lO.DET,. 
lO.FDX,. 
lO.HDX,. 
lO.INL,. 

lO.KIL,. 
lO.RLB, . 

lO.RNS, . 
lO.SYN,. 
lO.TRM, . 

lO.WLB, . 



. ,<stadd,size> 

. ,<stadd,size> 
. ,<syn> 

. ,<stadd,size> 



lO.WNS, , . . ,<stadd,size> 



Attach device 

Detach device 

Set device to full-duplex mode 

Set device to half-duplex mode 

Initialize device and set device 
characteristics 

Cancel I/O requests 

READ logical block, stripping 
sync characters 

READ logical block, transparent mode 

SPECIFY sync character 

Terminate communication, disconnecting 
from physical channel 

WRITE logical block with sync leader 

WRITE logical block, no sync leader 



A. 5 DECTAPE DRIVER 

10. RLE, . . . ,<stadd ,size, , ,lbn> 



lO.RLV,. 
lO.RVB,. 
lO.WLB,. 
lO.WLV, . 
lO.WVB, . 



. ,<stadd ,size , , ,lbn> 
. ,<stadd ,size, , ,lbn> 
. ,<stadd ,size , , ,lbn> 
. ,<stadd ,size , , ,lbn> 
. ,<stadd ,size , , ,lbn> 



READ logical block (forward) 
READ logical block (reverse) 
READ virtual block (forward) 
WRITE logical block (forward) 
WRITE logical block (reverse) 
WRITE virtual block (forward) 
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A. 6 DECTAPE II DRIVER 

ICATT.. 

lO.DET,. 

lO.KIL,. 

lO.RLB,. 

lO.WLB,. 

lO.WLC,. 

lO.RLC 

lO.BLS, . 

lO.DGN,.,. 



,<stadd,size, , ,lbn> 
,<stadd,size, , ,lbn> 
,<stadd,size, , ,lbn> 
,<stadd,si28, , ,lbn> 
,<lbn> 



Attach device 

Detach device 

Cancel I/O requests 

READ logical block 

WRITE logical block 

WRITE logical block with check 

POSITION tape 

Run internal diagnostics 



A. 7 DISK DRIVER 

10. RLE, . . . ,<stadd,size, ,blkh,blkl> 

lO.RPB, . . . ,<stadd ,size , , ,pbn> 

lO.RVB,. . . ,<stadd,size, ,blkh,blkl> 

10. SEC, . . . ,<stadd,size,pbn> 

lO.SMD, . . . ,<density, ,> 

lO.WDD, . . . ,<stadd ,size , , ,pbn> 



lO.WLB,. 
lO.WLC,. 

lO.WPB,. 
lO.WVB,. 



. ,<stadd ,size , ,blkh,blkl> 
. ,<stadd,size , ,blkh,blkl> 

. ,<stadd,size, , ,pbn> 

. ,<stadd,size, ,blkh,blkl> 



READ logical block 

READ physical block 

READ virtual block 

SENSE characteristics (RX02) only 

SET media density (RX02 only) 

WRITE physical block (with 
deleted data mark) 

WRITE logical block 

WRITE logical block followed 
by write check 

WRITE physical block 

WRITE virtual block 



A. 8 GRAPHICS DISPLAY DRIVER 
10. ATT, . 



10. CON, 
lO.CNT, 

lO.DET, 
lO.DIS, 
lO.KIL,, 
lO.STP,, 



,<stadd ,size,lpef ,lpast> 



Attach device 

CONNECT to graphics device 

Continue (restart display- 
processing unit) 

Detach device 

Disconnect from graphics device 

Cancel I/O requests 

Stop (halt display-processing 
unit) 
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A. 9 INDUSTRIAL CONTROL SUBSYSTEMS 

All I/O functions listed below apply to the ICS/ICR subsystem. The 
five functions supported by the DSS/DRSll subsystem driver are marked 
by (D). 



lO.CCI, . . . ,<stadd,sizb,tevf> 
lO.CTI, . . . ,<stadd ,sizb, tevf ,arv> 
lO.CTY, . . . ,<stadd,sizb,tevf> 
lO.DCI, 

10. DTI, . . . 

lO.DTY,. .. 

lO.FLN, . . . 

10. ITI, . . . ,<mn,ic> 

lO.LDI, . . . ,<tname, [ ,tevf] ,pn,csm> 

lO.LKE, . . . ,<tname, [ ,tevf] > 

lO.LTI, . . . ,<tname, [ ,tevf ] ,cn[ ,arv] > 

lO.LTY, . . . ,<tname, [ ,tevf ] > 

lO.MLO, . . . ,<opn,pp,dp> 

lO.MSO, . . . ,<opn,dp> 

lO.NLK, . . . ,<tname> 



lO.NLN, . . 
10. RAD, . . 
lO.RBC, . . 
10. SAO, . . 
lO.UDI, . . 



. ,<stadd> 

. ,<stadd ,size,stcnta> 

. ,<chn,vout> 

. ,<tname> 



CONNECT a buffer to digital 
interrupts 

CONNECT a buffer to counter 
interrupts 

CONNECT a buffer to terminal 
interrupts 

Disconnect a buffer from digital 
interrupts 

Disconnect a buffer from counter, 
interrupts 

Disconnect a buffer from terminal 
interrupts 

Set controller off line 

INITIALIZE a counter 

LINK task to digital interrupts 
(D) 

LINK task to error interrupts 

LINK task to counter interrupts 

LINK task to remote terminal 
interrupts 

OPEN or close bistable digital 
output points (D) 

PULSE single-shot digital output 
points 

UNLINK a task from all interrupts 
(D) 

Place ICR controller on line 

READ activating data (D) 

INITIATE multiple A/D conversions 

PERFORM analog output 

UNLINK a task from digital 
interrupts (D) 



SUMMARY OF I/O FUNCTIONS 



lO.UER, . . . ,<tname> 



lO.UTI, . . . ,<tname> 



lO.UTY, ... ,<tname> 



I0.WL3, . . . ,<staddb,sizb> 



UNLINK a task from error 
interrupts 

UNLINK a task from counter 
interrupts 

UNLINK a task from terminal 
interrupts 

TRANSMIT data to the ICR remote 
terminal 



A. 10 LABORATORY PERIPHERAL ACCELERATOR DRIVER 

lO.CLK, . . . ,<mode,ckcsr ,preset> 

10. INI, .. . ,<irbuf ,278.> 

lO.LOD, .. . ,<mbuf ,2048,> 

lO.STA, . . . ,<bufptr,40.> 

lO.STP, . . . ,<userid> 



A. 11 LABORATORY PERIPHERAL SYSTEMS DRIVERS 



10. ADS, . . . ,<stadd,size,pnt , 
ticks,buf s,chna> 

10. HIS, . . . ,<stadd,size,pnt , 
ticks, bufs> 

lO.KIL,... 

10. LED, . . . ,<int,num> 

lO.MDA, . . . ,<stadd ,size ,pnt, 
ticks, bufs,chnd> 

lO.MDI, . . . ,<stadd ,size,pnt, 
ticks, bufs, ma sk> 

lO.MDO, . . . ,<stadd,size,pnt, 
ticks, bufs, ma sk> 

lO.REL, . . . ,<rel,pol> 

lO.SDI, . . . ,<mask> 

lO.SDO, . . . ,<mask,data> 

lO.STP, . . . ,<stadd> 



PERFORM A/D sampling 

PERFORM histogram sampling 

Cancel I/O requests 

DISPLAY number in LED lights 

PERFORM D/A output 

PERFORM digital input sampling 

PERFORM digital output 

LATCH output relay 
READ digital input register 
WRITE digital output register 
STOP in-progress request 
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A. 12 LINE PRINTER DRIVER 

10. ATT,. 

lO.DET,. 



lO.KIL,. 
lO.WLB,. 
lO.WVB,. 



,<stadd ,size,vfc> 
,<stadd,size,vfc> 



Attach device 
Detach device 
Cancel I/O requests 
WRITE logical block 
WRITE virtual block 



. ,<stadd ,size> 
. ,<stadd,size> 
. ,<stadd,size> 



A. 13 MAGNETIC TAPE DRIVER 

10. ATT,. 

lO.DET,. 

10. EOF,. 

lO.KIL,. 

lO.RLB,. 

lO.RLV,. 

lO.RVB,. 

lO.RWD,. 

lO.RWU,. 

10. SEC,. 

lO.SMO,. 

lO.SPB, . 

lO.SPF,. 

lO.STC, . 

lO.WLB,. 

lO.WVB,. 



. ,<cb> 

. ,<nbs> 

. ,<nes> 

. ,<cb> 

. ,<stadd ,size> 

. ,<stadd ,size> 



Attach device 

Detach device 

Write end-of-file (tape mark) 

Cancel I/O requests 

READ logical block 

READ logical block reverse 

READ virtual block 

Rewind tape 

Rewind and turn unit off line 

Read tape characteristics 

MOUNT tape and set tape characteristics 

SPACE blocks 

SPACE files 

SET tape characteristics 

WRITE logical block 

WRITE virtual block 



A. 14 PAPER TAPE READER/PUNCH DRIVERS 

10. ATT,... Attach device 

lO.DET,... Detach device 

lO.KIL,... Cancel I/O Requests 

lO.RLB, . . . ,<stadd ,size> READ logical block (reader only) 
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lO.RVB,. . . ,<stadd,size> READ virtual block (reader only) 
lO.WLB, . .. ,<stadd,size> WRITE logical block (punch only) 
lO.WVB,. ..,<stadd,size> WRITE virtual block (punch only) 

A. 15 PARALLEL COMMDNICATION LINK DRIVERS 

A. 15.1 Transmitter Driver Functions 

lO.ATX, . . . ,<stadd,size,f lagwd, ATTEMPT message transmission 
id, retries ,retadd> 

10. STC,. .. ,<stadd, size, [state] SET master section characteristics 
[mode] , ,retadd> 

10. SEC,..., Sense master section status 

A. 15. 2 Receiver Driver Functions 

lO.CRX, . . . ,<tef> CORRECT for reception 

lO.ATF, . . . ,<stadd,size,retadd> ACCEPT transfer 

10. RTF,.., Reject transfer 

lO.DRX,... Disconnect from reception 

A, 16 TERMINAL DRIVER 

lO.ATA,. . .,<ast[ ,parameter2] ATTACH device, specify unsolicited- 
[,ast2]> character ASTl 

10. ATT,... Attach device 

lO.CCO, . . . ,<stadd,size,vfc> WRITE logical block, cancel CTRL/0 

lO.DET,... Detach device 

SF.GMC, . . . ,<stadd,size> GET multiple characteristics 

lO.GTS, . . . ,<stadd,size> GET terminal support 

lO.HNG,... HANGUP remote line 

lO.KIL,... Cancel I/O requests 

lO.RAL, . . . ,<stadd,size[ ,tmo] > READ logical block and pass all bitsl 

lO.RLB, . . . ,<stadd,size[ ,tmo] > READ logical blockl 

lO.RNE, . . . ,<stadd,size[,tmo] > READ logical block and do not echol 



1. "ast2", "parameter2", and "tmo" parameters are available for 
full-duplex driver functions only. 
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ICRPR, .. . ,<stadd,size, [tmo] , READ after promptl 
pradd,prsize,vfc> 

lO.RST, .. . ,<stadd,size[,tmo]> READ with special terminators 

lO.RTT,. . .,<stadd,size, [tmo] , READ logical block ended by specified 
table> special terminator2 

lO.RVB,. .. ,<stadd,size[,tmo]> READ virtual blockl 

SF.SMC,, .. ,<stadd,size> SET multiple characteristics 

lO.WAL, . . . ,<stadd,size,vfc> WRITE logical block and pass all bits 

lO.WBT,.. . ,<stadd,size,vfc> WRITE logical block and break through 

any ongoing I/O 

lO.WLB, . .. ,<stadd,size,vfc> WRITE logical block 

lO.WVB, , . . ,<stadd,size,vfc> WRITE virtual block 

Subfunction bits for terminal-driver functions: 

TF.AST Unsolicited-input-character AST 

TF.BIN Binary prompt 

TF.CCO Cancel CTRL/0 

TF.ESQ Recognize escape sequences 

TF.NOT Unsolicited input AST notif ication2 

TF.RAL Read, pass all bits 

TF.RCU Restore cursor positions 

TF.RNE Read with no echo 

TF.RST Read with special terminators 

TF.TMO Read with time-out2 

TF.WAL Write, pass all bits 

TF.WBT Break-through write 

TF.XCC CTRL/C starts a command line interpreters 

TF.XOF Send XOFF 



T ii_^i_-)ii ii_^„3_„4._^9 11 3r>^ "Fmo" naramol-or c 3i-(= available for 

full-duplex driver functions only. 



2. Full-duplex driver only. 
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A. 17 UNIBUS SWITCH DRIVER 
lO.ATT,.. . ,<[ast] > 
lO.DET, 



lO.KIL,. 
lO.CON,. 
QIO$C 10 
10. DPT,. 



. ,< [rent] , [cpu] > 
DIS, . . . , 
.,<[tout] , [port]> 



lO.SWI, ,<cpu> 



lO.CSR, 



ATTACH device 

Detach device 

Cancel I/O requests 

CONNECT UNIBUS switch 

Disconnect UNIBUS switch 

DISCONNECT UNIBUS switch and connect 
to specified CPU port 

SWITCH UNIBUS from current CPU to 
specified CPU 

Read UNIBUS switch CSR 



A. 18 UNIVERSAL DIGITAL CONTROLLER DRIVER 

lO.CCI, ,<stadd,sizb,tevf> CONNECT a buffer to contact 

interrupts 

lO.CTI, ,<stadd,sizb,tevf ,arv> CONNECT a buffer to timer 

interrupts 



lO.DCI, . . . 

10. DTI,... 

10. ITI, . . • ,<mn,ic> 

lO.KIL,. .. 

lO.MLO, . . . ,<opn,pp,dp> 

lO.RBC, . . . ,<stadd ,size ,stcnta> 



Disconnect a buffer from contact 
interrupt 

Disconnect a buffer from timer 
interrupts 

INITIALIZE a timer 

Cancel I/O requests 

OPEN or close latching digital 
output points 

INITIATE multiple A/D conversions 



A. 19 VIRTUAL TERMINAL DRIVER 

10. ATT,. 

lO.DET,. 

lO.KIL,. 

lO.RLB, . 

lO.RVB,. 

lO.WLB, . 

lO.WVB,. 

lO.STC, . 



,<stadd ,size> 
,<stadd ,size> 



Attach device 
Detach device 
Cancel I/O request 
READ logical block 
READ virtual block 



,<stadd ,size ,stat> WRITE logical block 
,<stadd,size,stat> WRITE virtual block 
,<cb,sw2,swl> 



SET terminal characteristics (enable/ 
disable intermediate buffering, or 
return I/O completion status) 
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APPENDIX B 
I/O FUNCTION AND STATUS CODES 



This appendix lists the numeric codes for all I/O functions, directive 
status returns, and I/O completion status returns. Lists are 
organized in the following sequence: 

• I/O completion status codes 

• Directive status codes 

• Device-independent I/O function codes 

• Device-dependent I/O function codes 

Device-dependent function codes are listed by device. Both devices 
and codes are organized in alphabetical order. 

For each code, the symbolic name is listed in form lO.xxx, lE.xxx, or 
IS. XXX. A brief description of the error or function is also 
included. Both decimal and octal values are provided for all codes. 



B.l I/O STATUS CODES 

This section lists error and success codes which can be returned in 
the I/O status block on completion of an I/O function. The codes 
below may be referenced symbolically by invoking the system macro 
IOERR$. 



B.1.1 I/O Status Error Codes 

Name Decimal Octal Meaning 

IE. ABO -15 177761 Operation aborted 

lE.ALN -34 177736 File already open 

IE. BAD -01 177777 Bad parameter 

lE.BBE -56 177710 Bad block 

lE.BCC -66 177676 Block check error or framing error 
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Name 


Decimal 


Octal 


lE.BLK 


-20 


177754 


IE. BYT 


-19 


177755 


IE. CNR 


-73 


177667 


IE. CON 


-22 


177752 


lE.DAA 


-08 


177770 


lE.DAO 


-13 


177763 


lE.DNA 


-07 


177771 


lE.DNR 


-03 


177775 


IE. DUN 


-09 


177767 


IE. EOF 


-10 


177766 


IE. EOT 


-62 


177702 


lE.EOV 


-11 


177765 


lE.FHE 


-59 


177705 


lE.FLG 


-89 


177647 


lE.FLN 


-81 


177657 


lE.IEF 


-97 


177637 


lE.IES 


-82 


177656 


lE.IFC 


-2 


177776 


IE. MOD 


-21 


177753 


lE.NLK 


-79 


177661 


lE.NLN 


-37 


177733 


IE. NOD 


-23 


177751 



lE.NST 


-80 


177660 


lE.NTR 


-87 


177651 


lE.OFL 


-65 


177677 


lE.ONP 


-05 


177773 



Meaning 

Illegal block number 

Byte-ligned buffer specified 

Connection rejected 

UDC connect error 

Device already attached 

Data overrun 

Device not attached 

Device not ready 

Device not attachable 

End-of-file encountered 

End-of-tape encountered 

End-of-volume encountered 

Fatal hardware error 

Event flag already specified 

ICS/ICR controller already offline 

Invalid event flag 

Invalid escape sequence 

Illegal function 

Invalid UDC or ICS/ICR module 

Task not linked to specified 
ICS/ICR interrupts 

File not open 

No dynamic memory available to 
allocate a secondary control 
block 

Task specified in ICS/ICR Link or 
Unlink request not installed 

Task not triggered 

Device off line 

Illegal subfunction 
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Name Decimal Octal Meaning 

lE.OVR -18 177756 Illegal read overlay request 

IE. PES -83 177655 Partial escape sequence 

lE.PRI -16 177760 Privilege violation 

lE.REJ -88 177650 Transfer rejected 

IE. NOD -23 177751 No dynamic memory available 

lE.RSU -17 177757 Nonsharable resource in use 

lE.SPC -06 177772 Illegal address space 

lE.TMO -74 177666 Time-out error 

lE.VER -04 177774 Unrecoverable error 

lE.WCK -86 177652 Write check error 

lE.WLK -12 177764 Write-locked device 



B.1.2 I/O Status Success Codes 





Decimal 




Octal 


Name 


Bytes 




Word 


IS.CR 


Byte 


0: 


1 


006401 




Byte 


1: 


15 




IS.CC 


Byte 


0: 


1 


001401 




Byte 


1: 


3 




IS. ESC 


Byte 


0: 


1 


015401 




Byte 


1: 


33 




IS. ESQ 


Byte 


0: 


1 


115401 




Byte 


1: 


233 




IS.PND 


+00 






000000 


IS.RDD 


+02 






000002 


IS. sue 


+01 






000001 


IS.TMO 


+02 






000002 


IS.TNC 


+02 






000002 



Meaning 

Successful completion with 
carriage return 

Successful completion on 
read terminated by CTRL/C 

Successful completion 
with ESCape 

Successful completion with 
an escape sequence 

I/O request pending 

Deleted data mark read 

Successful completion 

Successful completion on 
read terminated by time-out 

Successful transfer but 
message truncated (receiver 
buffer too small) 
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B.2 DIRECTIVES CODES 

This section lists error and success codes that can be returned in the 
directive status word at symbolic location $DSW when a QIO directive 
is issued. 



B.2.1 Directive Error Codes 



Name 


Decimal 


Octal 


lE.ADP 


-98 


177636 


lE.IEF 


-97 


177637 


lE.ILU 


-96 


177640 


lE.SDP 


-99 


177635 


lE.ULN 


-05 


177773 


lE.UPN 


-01 


177777 



Meaning 
Invalid address 
Invalid event flag number 
Invalid logical unit number 
Invalid DIC number or DPB size 
Unassigned LUN 
Insufficient dynamic storage 



B.2. 2 Directive Success Codes 
Name Decimal Octal 

IS. sue +01 000001 



Meaning 
Directive accepted 



B.3 I/O FUNCTION CODES 

This section lists octal codes for all standard and device-dependent 
I/O functions. 



B.3.1 Standard I/O Function Codes 



Symbolic 
Name 


Word Equivalent 


Coc 
(High 


10. ATT 


001400 


3 


lO.DET 


002000 


4 


lO.KIL 


000012 





lO.RLB 


001000 


2 


lO.RVB 


010400 


21 


lO.WLB 


000400 


1 


lO.WVB 


011000 


22 



Subcode 
(Low Byte) Meaning 

Attach device 

Detach device 

12 Cancel I/O requests 

Read logical block 

Read virtual block 

Write logical block 

Write virtual block 
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B.3.2 Specific A/D Converter I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) 



lO.RBC 



003000 







Meaning 

Initiate an A/D 
conversion 



B.3.3 Specific Card Reader I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) 



lO.RDB 



001200 



200 



Meaning 

Read logical block 
(binary) 



B.3.4 Specific Cassette I/O Function Codes 



Symbolic 
Name 

10. EOF 



lO.RWD 
lO.SPB 
lO.SPF 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 

003000 6 



002400 
002420 
002440 





20 

40 



Meaning 

Write end-of-file 
gap 

Rewind tape 

Space blocks 

Space files 



B.3.5 Specific Communication (Message-Oriented) I/O Function Codes 



Symbolic 
Name 

lO.FDX 



lO.HDX 



lO.INL 



lO.RNS 



lO.SYN 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



003020 



003010 



002400 



001020 



003040 



20 



10 



20 



40 



Meaning 

Set device to 
full-duplex mode 

Set device to 
half-duplex mode 

Initialize device 
and set device 

characteristics 

Read logical block, 
transparent mode 

Specify sync 
character 



lO.TRM 



lO.WNS 



002410 



000420 



10 Terminate 

communication, 
disconnecting from 
physical channel 

20 Write logical block 
with no sync leader 
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B.3.6 Specific DECtape I/O Function Codes 



Symbolic 
Name 

lO.RLV 



lO.WLV 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



001100 



000500 



100 



100 



Meaning 

Read logical block 
(reverse) 

Write logical block 
(reverse) 



B.3.7 Specific DECtape II I/O Function Codes 



Symbolic 
Name 

lO.WLC 



lO.RLC 

lO.BLS 
lO.DGN 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



420 

1020 

4010 
4150 



10 
10 



20 

20 

10 
150 



Meaning 

Write logical block 
with check 

Read logical block 
with check 

Position tape 

Run internal 
diagnostics 



B.3.8 Specific Disk I/O Function Codes 



Symbolic 
Name 

lO.RPB 



10. SEC 



lO.SMD 



lO.WDD 



lO.WLC 



lO.WPB 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



001040 



002520 



002500 



001140 



001020 



000440 



40 



120 



100 



140 



20 



40 



Meaning 

Read physical block 
(RXOl, RLOl, RL0 2 
only) 

Sense 

characteristics 
(RX02 only) 

Set media density 
(RX02 only) 

Write physical block 
with deleted data 
mark (RX02 only) 

Write logical block 
followed by write 
check (all except 
RXOl, RX02) 

Write physical block 
(RXOl, RX0 2, RLOl, 
RL02 only) 
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00 


Connect to graphics 




device 


00 


Continue DPU 


00 


Disconnect from 




graphics device 


00 


Stop DPU 



I/O FUNCTION AND STATUS CODES 



B.3.9 Specific Graphics Display I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

10. CON 015400 33 



lO.CNT 017000 36 
lO.DIS 016000 34 

lO.STP 016400 35 



B.3,10 Specific ICS/ICR, DSS/DR I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

lO.CCI 014000 30 Connect a buffer to 

digital interrupt 
input 

Connect a counter 

Connect a remote 
terminal 

Disconnect a buffer 
from digital 
interrupt input 

Disconnect a buffer 
from counter input 

Disconnect a buffer 
from terminal input 

Place selected unit 
off line 

Initialize a counter 

Link a task to 

digital interrupts 

Link a task to error 
interrupts 

Link a task to 

counter interrupts 

Link a task to 

terminal interrupts 



lO.CTI 


015400 


33 


lO.CTY 


003400 


7 


lO-DCI 


014400 


31 



10. DTI 


016000 


34 


lO.DTY 


006400 


15 


lO.FLN 


012400 


25 


lO.ITI 


017000 


36 


lO.LDI 


007000 


16 


lO.LKE 


012000 


24 


lO.LTI 


007400 


17 


lO.LTY 


010000 


20 
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Symbolic 
Name 

lO.MLO 



lO.MSO 



lO.NLK 



lO.ONL 



ID, RAD 



lO.RBC 



10. SAO 



lO.UDI 



lO.UER 



lO.UTI 



lO.UTY 



lO.WLB 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



006000 



005000 



011400 



017400 



010400 



003000 



004000 



011410 



011440 



011420 



011430 



000400 



14 



12 



23 



37 



21 







10 



23 



23 



23 



23 



10 



40 



20 



30 



Meaning 

Open or close 
bistable digital 
output points 

Pulse single-shot 
digital output 
points 

Unlink a task from 
all unsolicited 
interrupts 

Place selected unit 
on line 

Read task activation 
data 

Initiate multiple 
A/D conversions 

Perform analog 
output to specified 
channel 

Unlink a task from 
digital interrupts 

Unlink a task from 
error interrupts 

Unlink a task from 
counter interrupts 

Unlink a task from 
terminal interrupts 

Output to remote 
terminal 



B.3.11 Specific LPAll-K I/O Function Codes 



Symbolic 
Name 

lO.CLK 

10. INI 

lO.LOD 

lO.STA 

lO.STP 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



015000 
014400 
014000 
015400 



32 

31 
30 
33 
35 



Meaning 
Start clock 
Initialize LPAll-K 
Load microcode 
Start transfer 
Stop request 
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B.3.12 Specific LPS I/O Function Codes 

Symbolic code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

lO.ADS 014000 30 Initialize A/D 

sampling 

lO.HIS 015000 32 Initialize histogram 

sampling 

Display number in 
LED lights 

Initialize D^A 
output 

Initialize digital 
input sampling 

Initialize digital 
output 

Latch output relay 

Read digital input 
register 

Write digital output 
register 

Stop in-progress 
request 



B.3.13 Specific Magtape I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 



10. LED 


012000 


24 


lO.MDA 


016000 


34 


lO.MDI 


014400 


31 


lO.MDO 


015400 


33 


lO.REL 


013400 


27 


lO.SDI 


013000 


26 


lO.SDO 


012400 


25 


lO.STP 


016400 


35 



10. EOF 


003000 


6 


lO.RLV 


001100 


2 


I . RWD 


002400 


5 


lO.RWU 


002540 


5 


10. SEC 


002520 


5 


lO.SMO 


002560 


5 


lO.SPB 


002420 


5 


lO.SPF 


002440 


5 


lO.STC 


002500 


5 






Write end-of-file 




gap 


100 


Read logical block 




(reverse) 





Rewind tape 


140 


Rewind and unload 


120 


Sense 




characteristics 



160 Mount and set 

characteristics 

20 Space blocks 

40 Space files 

100 Set characteristics 
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B.3.14 Specific Parallel Communications Link I/O Function Codes 
B. 3. 14.1 Transmitter Driver Functions - 



Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) 



10. ATX 



lO.STC 



10. SEC 



000400 



002500 



002520 







Meaning 

Attempt message 
transmission 



100 Set master section 
characteristics 

120 Sense master section 
status 



B.3.14. 2 Receiver Driver Functions 



Symbolic 
Name 

lO.CRX 



lO.ATF 
10, RTF 
lO.DRX 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



014400 

001000 
015400 
001500 



31 

2 

33 
32 



Byte) 


Meaning 





Conneect for 




reception 





Accept transfer 





Reject transfer 





Disconnect from 




reception 



B.3.15 B.3.15 Specific Terminal I/O Function Codes 



Symbolic 
Name 

10. ATA 



Code Subcode 
Word Equivalent (High Byte) (Low Byte) 



001410 



lO.CCO 


000440 


1 


SF.GMC 


002560 


5 


10. GTS 


002400 


5 


lO.HNG 


003000 


6 


lO.RAL 


001010 


2 



10 

40 

160 

00 



10 



Meaning 



Attach device, 
specify 

unsolicited- input- 
character AST 

Write logical block 
and cancel CTRL/0 

Get multiple 
characteristics 

Get terminal support 

HANGUP remote line 

Read logical block 
and pass all bits 



anr 1 1 1 QST 



I/O FUNCTION AND STATUS CODES 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

lO.RNE 001020 2 20 Read with no echo 

10, RPR 004400 11 00 Read after prompt 

lO.RST 001001 2 1 Read with special 

terminators 

lO.RTT 005001 12 1 Read logical block 

ended by specified 
special terminator 
(Full-duplex driver 
only) 

SF.SMC 002440 5 40 Set multiple 

characteristics 

lO.WAL 000410 1 10 Write logical block 

.nd pass all bits 

10. WET 000500 1 100 Write logical block 

and break through 



on-going I/O 



Subfunction Bits: 



With lO.RLB, 10. RPR: 

TF.RST 1 

TF.BIN 2 

TF.RAL 10 

TF.RNE 20 

TF.XOF 100 

TF.TMO 200 



With lO.WLB; 



TF.WAL 10 

TF.CCO 40 

TF.WBT 100 



With 10. ATT: 



TF.AST 10 

TF.ESQ 20 
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10. DTI 


016000 


34 


lO.ITI 


017000 


36 


lO.MLO 


006000 


14 



I/O FUNCTION AND STATUS CODES 

B.3.16 Specific UDC I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

lO.CCI 014000 30 Connect a buffer to 

contact interrupt 
digital input 

lO.CTI 015400 33 Connect a timer 

lO.DCI 014400 31 Disconnect a buffer 

from contact 
interrupt digital 
input 

Disconnect a timer 

Initialize a timer 

Open or close 

latching digital 
output points 

lO.RBC 003000 6 Initiate multiple 

A/D conversions 



B.3.17 Specific UNIBUS Switch I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

10. CON 15400 33 Connect UNIBUS 

switch 

lO.DIS 16000 34 Disconnect UNIBUS 

switch 

10. DPT 16010 34 10 Disconnect UNIBUS 

switch and connect 
to specified CPU 
port 

lO.SWI 16400 35 Switch UNIBUS from 

current CPU to 
specified CPU 

lO.CSR 15000 32 Read UNIBUS switch 

CSR 



B.3.18 Specific Virtual Terminal I/O Function Codes 

Symbolic Code Subcode 

Name Word Equivalent (High Byte) (Low Byte) Meaning 

lO.STC 002500 5 100 Set terminal 
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APPENDIX C 
QIO INTERFACE TO THE ACPS 



This appendix describes the QIO level interface to the file processors 
(ACPs) . These include FllACP for Files-11 disks and MTAACP for ANSI 
magnetic tape. 

FllACP supports the following functions: 

lO.CRE Create file 

10, DEL Delete file 

lO.ACR Access file for read only 

lO.ACW Access file for read/write 

10. ACE Access file for read/write/extend 

lO.DAC Deaccess file 

10. EXT Extend file 

10. RAT Read file attributes 

10. WAT Write file attributes 

lO.FNA Find file name in directory 

lO.RNA Remove file name from directory 

lO.ENA Enter file name in directory 

lO.ULK Unlock block 

MTAACP supports the following functions: 

lO.FNA Find file by name 

lO.ENA Enter name in directory (a no-op) 

lO.ACR Access for read only 

lO.ACW Access for read/write 

10. ACE Access for read/write/extend 

lO.DAC Deaccess file 

lO.RVB Read virtual block 

lO.WVB Write virtual block 

10. EXT Extend file 

lO.CRE Create file 

10. RAT Read attributes 

lO.APC ACP control 

lO.APV Privileged ACP control 



C.l QIO PARAMETER LIST FORMAT 

The device-independent part of a file processing QIO parameter list is 
identical to all other QIO parameter lists. The general QIO parameter 
lists is described in detail in Section 1.6 of this manual. The file 
processor QIOs require the following six additional words in the 
parameter lists: 

Parameter Word 1 Address of a 3-word block containing the 

file identifier 
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Parameter Word 2 
Parameter Words 3 & 4 
Parameter Word 5 

Parameter word 6 



Address of the attribute list 

Size and extend control information 

Window size information and access 
control 

Address of the file name block 



NOTE 

The RSX-llM/M-PLUS Executive treats File 
Identifier Blocks, filename blocks, and 
attribute list entries as read/write 
data. For this reason, they may not be 
used in read-only code segments or 
libraries. 



C.1.1 File Identification Block 

The File Identification Block is a 3-word block containing the file 
number and the file sequence number. The format of the File 
Identification Block is shown in Figure C-1. 



File Number 



File Sequence Number 



Reserved 



Figure C-1 File Identification Block 



FllACP uses the file number as an index to the file header in the 
index file. Each time a header block is used for a new file, the file 
sequence number is incremented. This insures that the file header is 
always unique. The third word is not currently used but is reserved 
for the future. 



C.1.2 The Attribute List 

The file attribute list controls FllACP reads or writes. File 
attributes are fields in the file header. These fields are described 
in detail in Appendix F of the lAS/RSX I/O Operations Reference 
Manual . 

The attribute list contains a variable number of entries terminated by 
an all-0 byte. The maximum number of entries in the attribute list is 
six . 

An entry in the attribute list has the following format: 

.BYTE <Attribute type> , Attribute size 
.WORD Pointer to the attribute buffer 
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C. 1.2.1 The Attribute Type - This field identifies the individual 
attribute to be read or written. The sign of the attribute type code 
determines whether the transfer is a read or write operation. If the 
type code is negative, the ACP reads the attribute into the buffer. 
If the type code is positive, the ACP writes the attribute to the file 
header. Note that the sign of the type code must agree with the 
direction implied by the operation. For example, if the type code is 
positive, the operation must be an 10. WAT or lO.DAC. 

The attribute type is one of the following: 

• File owner (H.FOWN) 

The file owner UIC is a binary word. The low byte is the 
owner number and the high byte is the group number. 

• File protection (H.FPRO) 

The file protection word is a bit mask with the following 
format : 

Each of the fields contains four bits, as follows: 

Bit 1 Read Access 

Bit 2 Write Access 

Bit 3 Extend Access 

Bit 4 Delete Access 

• File characteristics (H.UCHA) 

The following user characteristics are currently contained in 
the 1-byte H.UCHA field: 

UC.CON = 200 Logically contiguous file 
UC.DLK = 100 File improperly closed 

• Record I/O Area (U.UFAT) 

This field contains a copy of the first sevenl words of the 
file descriptor block. See Appendix A of the lAS/RSX I/O 
Operations Reference Manual for a description of the FDB. 

• File name (I.FNAM) 

The file name is stored as nine Radix-50 characters. the 
fourth word of this block contains the file type and the fifth 
word contains the version number. 

• File type (I.FTYP) 

The file type is stored as three Radix-50 characters. 

• Version number (I.FVER) 

The version number is stored as a binary number. 

• Expiration date (I.EXDT) 
Creation date (I.CRDT) 
Revision date (I.RVDT) 

The expiration date is currently unused. When the file is 

created, the ACP initializes the creation date to the current 

date and time. It initializes the expiration and revision 

dates to 0. The ACP sets the revision date to the current 
date and time each time the file is deaccessed. 



1. RMS uses 32 bytes. The first seven are compatible with FCS for 
sequential files. 
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Statistics block 

This block is described in Appendix H of the lAS/RSX I/O 

Operations Reference Manual . 



Read entire file header 

This buffer is assumed to be 1000 blocks long, 

write this attribute. 



You cannot 



Revision number (I.RVNO) 

The ACP sets the revision number to 0, and increments it every 

time the file is deaccessed. 

Placement Control 



C.1.2.2 Attribute Size - This word specifies the number of bytes of 
the attribute to be transferred. Legal values are from 1 to the 
maximum size of the particular attribute. Table C-1 shows the maximum 
size for each attribute type. 



Table C-1 
Maximum Size for Each File Attribute 







Maximum 


Attribute 


Attribute 


Attribute Size 


Type Code 


Type 


in Octal Bytes 


1 


File owner 


6 


2 


Protection 


4 


3 


File characteristics 


2 


4 


Record I/O area 


40 


5 


File name , type , version number 


12 


(5 


File type 


4 


7 


Version number 


2 


10 


Expiration date 


7 


11 


Statistics block 


12 


12 


Entire file header 





13 


Block Size (magtape only) 


— 


15 


Revision number and 






creation/revision/expiration dates 


43 


16 


Placement control 


16 
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C. 1.2.3 Attribute Buffer Address - The attribute Buffer Address field 
contains the address of the buffer in the user's task space to or from 
which the attribute is to be transferred. 



C.1.3 Size and Extend Control 

These two parameters specify how many blocks the file processor 
allocated to a new file or adds to an existing file. These parameters 
also control the type of block allocation. 

The format is as follows: 

.^^j.^ viij-vjn B uiua Kjs. size>', <excend controi> 
.WORD <Low 16 bits of size> 

The size field specifies the number of blocks to be allocated to a 
file on lO.CRE and 10. EXT operations, and the final file size on 
10. DEL operations. 

The extend control field controls the manner in which an extend 
operation is to be done. The following bits are defined: 

EX.AC1=1 The extend size is to be added as a contiguous 
block. 

EX.AC2=2 Extend by the largest available contiguous piece up 
to the specified size. 

EX.FC0=4 The file must end up contiguous. 

EX.ADF=10 Use the default rather than the specified size. The 
default extend size is the size that was specified 
when the volume was mounted. 

EX.ALL=20 Placement control (see Section C.2). 

EX.ENA=200 Enable extend. 



C.1.4 Window Size and Access Control 

This parameter specifies the window size and access control 
information in the following format: 

.BYTE <window size>, <access control> 

This word is only processed if the high bit of the access control bvte 
(AC.ENB) is set. 

Window size is the number of mapping entries. Specifying a negative 
window size minimizes window turns. if this byte is zero, the file 
processor uses the volume default. The size of the window allocated 
in the dynamic storage region is 6 times the number of mapping entries 
(each mapping entry is 3 words) , plus 10 bytes for the window control 
block. 
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On RSX-llM-PLUS systems with secondary pool support, the mapping 
entries are allocated in secondary pool. The window control block and 
a pointer to secondary pool are located in primary pool. 

The following access control bits are defined: 

AC.LCK=1 Lock out further accesses for Write or Extend 

AC.DLK=2 Enable Deaccess lock 

The deaccess lock sets the lock bit in the file header 
if the file is deaccessed as the result of a task 
exit without explicitly deaccessing the file. The 
lock bit is set by the executive. The lock bit is not 
set when the system crashes. 

AC.LKL=4 Enable block locking 

AC.EXL=10 Enable explicit block unlocking 

AC.ENB=200 Enable Access 

AC.RWD=10 Rewind the volume (labeled and unlabeled magtape only) 

AC.UPD=100 Update mode (labeled magtape only) 

AG.POS=20 Do Not Position to end-of- volume (labeled magtape 
only) 

AC.WCK=40 Initiate driver write-checking 

NOTE 

Both AC.LKL and AC.EXL must be set if 

you want block locking. If you do not 

want block locking, both bits must be 

clear. Any other combination is an 
error . 



C.1.5 File Name Block Pointer 

This word contains the address of a 15-word block in the issuing 
task's space. This block is called the file name block. The file 
name block is described in detail in Appendix B of the lAS/RSX I/O 
Operations Reference Manual . 

The fields of the file name block that are particularly important in 
file-processing operations are: 

• Directory identification (N.DID) 

This field is required for all disk operations. It specifies 
the directory to which the operation applies. This field is 
not used for tape operations. 

• File identification (N.FID) 

This field is required as input for enter operations. This 
field is returned as output by find and remove operations. 

• File name (N.FNAM), type (N.FTYP) , and version number (N.FVER) 
These fields are required as input to enter, find, and remove 
operations. For find and remove operations, the file 
processor locates the appropriate entry by matching the 
information in these fields with the directory entries. 

• Status word (N.STAT) 

• Wii-UCdEu CuuucXi- \vi .itiji^i. I 

This field is required as input for wildcard operations. It 
specifies the point at which to resume processing. It is 
updated for the next operation. It must initially be set to 

o". 
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C.2 PLACEMENT CONTROL 

The placement control attribute list entry controls the placement of a 
file in a particular place on the disk. You can specify either exact 
or approximate placement on lO.CRE and lO.EXT operations. 

The placement control entry must be the first entry in the attribute 
list. 

The format of the placement control attribute list entry is as 
follows: 

•BYTE placement control, 
.WORD high-order bits of VBN or LBN 
.WORK low-order bits of VBN or LBN 

•BLKW 4 ; Buffer to receive starting and ending LBN if 
AL.LBN is set. 

The following bits are defined for the placement control field: 

AL.VBN=1 Set if block specified is a VBN; otherwise, the 

block is the LBN 
AL.APX=2 Set if you want approximate placement; 

otherwise, placement is exact 
AL.LBN=4 Set if you want starting and ending LBN information 



C.3 BLOCK LOCKING 

Block locking only occurs when the user accesses a file with AC.LKL 
and AC.EXL set in the access control byte of the parameter list. Any 
read or write operation causes a check to see if the block is locked. 

A write access locks a block for exclusive access. A write operation 
can only access a block that is not locked by any accessor. The only 
exception to this is an exact match with a previous lock owned by the 
same accessor. 

A read access locks a block for shared access. A read operation can 
access any block locked for shared access. 

The user must unlock a block with an explicit unlock request, lO.ULK. 
lO.ULK may be used to unlock one or all blocks. 

If all accessors to a file have not requested block locking, the ACP 
returns an error (see Table C-2) . 

When the file is deaccessed, all locks owned by the accessor are 
released. 

Each active lock requires eight bytes from the dynamic storage region. 
This storage is deallocated when the file is deaccessed. 



C.4 SUMMARY OF FllACP FUNCTIONS 

The following is a summary of the functions implemented in FllACP. A 
list of accepted parameters follows each function. All parameters are 
required unless specified as optional. Parameters other than those 
listed are illegal for that function and must be 0. 
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lO.CRE Create file 



#1 The file identifier block is filled in with the file 
identifier and sequence number of the created file. 

#2 Write Attribute and/or Placement Control list 
(optional) 

#3 & #4 Extend Control (optional) 

The amount allocated to the file is returned in the 
high byte of lOST(l) plus I0ST(2). 

#5 May be nonzero but must be disabled 

10. DEL Delete or truncate file 

#1 Optional if the file is accessed 

#3 & #4 Size to truncate the file to. If not enabled, the 
file is deleted. If enabled, the remaining 31 bits 
specify the size the file is to be after truncation. 
The change in file allocation is returned in the high 
byte of lOST(l) plus I0ST(2). This amount will be 
zero or negative. 

lO.ACR Access file for read only 

lO.ACW Access file for read/write 

10. ACE Access file for read/write/extend 

#1 File identifier pointer 

#2 Read attributes control (optional) 

#5 Access control must be enabled 

lO.DAC Deaccess file 

#1 File identifier pointer (optional) 

#2 Write attributes control list 

#5 May be nonzero but must be disabled 

10. EXT Extend file 

#1 Optional if file is accessed 

#2 Placement control attribute list (optional) 

#3 & #4 Extend control 

The amount allocated to the file is returned in the 
high byte of lOST(l) plus I0ST(2). 

10. RAT Read attributes 

#1 Optional if file is accessed 

#2 Read attributes control list 

lO.FNA Find name in directory 

lO.RNA Remove name from directory 
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lO.ENA Enter name in directory 

#5 May be nonzero but must be disabled 
#6 File name block pointer 
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lO.ULK Unlock block 

#2 or count of blocks to unlock 

#4 & #5 Starting VBN to unlock or to unlock all blocks. 
lO.RVB Read virtual block 

lO.WVB Write virtual block 

#1 User buffer 

#2 Buffer length 

#4 & #5 VBN 

C.5 SUMMARY OF MTAACP FUNCTIONS 

The following is a summary of the functions implemented in MTAACP. A 
list of accepted parameters follows each function. All parameters are 
required unless specified as optional. Parameters other than those 
listed are illegal for that function and must be 0. 

lO.FNA Find file by name 

#5 AC.RWD set in the access control byte indicates 
that the volume is to be rewound prior to the 
search. 

#6 Pointer to file name block. 

The following fields are used as input: 

N.FNAM 
N.FTYP 
N.FVER 
N.STAT 

The following fields are returned by MTAACP: 

N.FID 

N.FNAM 

N.FTYP 

N.FVER 

N.STAT 

lO.ENA Enter name in directory — a no-op for magnetic tape 

lO.ACR Access for read only 

#1 File identifier pointer. Used to position a 
tape by file identifier. 

#2 Read attribute list (optional) 

#5 Ignored 

lO.ACW Access for read/write 

This function will be rejected with the error 
code lE.PRI. (Extend access is required.) 
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10. ACE Access for read/write/extend 

#1 File identifier pointer. Used to position tape 
by file identifier. 

#2 Read attribute list (optional) 

#5 AC.UPD (update mode). If AC.UPD is set, the 
tape will be positioned to overwrite the file 
and all files beyond the current file will be 
lost. If AC.UPD is not set, the tape will be 
positioned for append. If the file is not the 
last file, MTAACP returns the error code 
lE.ISQ. 

lO.DAC Deaccess file 

#1 File identifier pointer is ignored. 

#5 AC.RWD set indicates that the volume is to be 
rewound after the file is closed. 

lO.RVB Read virtual block 

#1 Buffer address 

#2 Buffer size. The buffer size must be greater 
than 18 bytes and less than the declared block 
length for the entire file. 

#4 High VBN 

#5 Low VBN 

The virtual block number must be either zero or exactly one 
greater than the previous block number. 

lO.CRE Create File 

#1 File identifier pointer. The file sequence and 
section number will be returned to the user's 
file identifier block. 

#2 Attribute list pointer. Used to write the 
attributes for the newly created file. 
Attribute type code must be positive. 

#5 If AC.RWD is set, the volume will be positioned 
at the beginning and will overwrite the first 
file. This effectively reinitializes the 
volume. 

If AC.RWD is not set and AC.POS is set, the 
volume set will be positioned to the next file 
position beyond the current file and will 
overwrite that file. All files beyond that on 
the volume will be destroyed. 

If neither AC.RWD nor AC.POS is set, the volume 
set will be positioned at its end and the new 
■F -i 1 o w"t T 1 i^o ^'0'**enc3sd to tlis sst > 

For unlabeled tapes, MTAACP only checks AC.RWD. 

#6 Filename block pointer. 
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10, RAT Read Attributes 

#1 File identifier pointer. Used to position the 
tape by the file identifier, 

#2 Attribute list pointer (see Section C.1.2) 

The following attribute list entries are 
meaningful for magnetic tape: 

1,2 UIC 

1.4 UIC and protection 

1.5 UIC, protection, and characteristics 

2.2 Protection 

2.3 Protection and characteristics 

3.1 Characteristics 
4,32 User file attributes 

5.6 File name 

5,8 File name and type 

5,10 File name and type 

6.2 File type 

6.4 File type and version number 
7,2 Version number 

8.7 Expiration date 

-9,10 Statistics block (read only) 
-10,0 Entire header (read only) 
11,2 Block size 

lO.APC ACP Control 

#3 One of the following user control function 
codes: 

1 Rewind volume set. 

2 Position to end of volume set. 

3 Close current volume and continue 
processing the next section of the same 
file on the next volume of the volume 
set. 

4 Space physical records in currently 
accessed file. 

5 Get ACP characteristics. 

6 Rewind current file. 

lO.APV Privileged ACP Control 

This function is used only by the MOUNT and DISMOUNT 

commands. This interface is subject to change and, 

therefore, will not be documented until a future 
release. 



C.6 HOW TO USE THE ACP QIOS 

Although the operations described in this appendix are normally 
performed by the file-access methods (RMS and FCS) , your application 
may issue the ACP QIOs. The required parameters for each QIO are 
described above. The necessary steps for common operations are 
described below. 



NOTE 

The file identifier is the only way to 
refer to a file. 
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C.6.1 Creating a File 
To create a file: 

• Use lO.CRE to create it. 

• Enter it in the Master File Directory (MFD) or a user 
directory with lO.ENA. 



C.6.2 Opening a File 
To open a file: 

• Use lO.FNA to find the File Identifier of the directory in the 
MFD. 

• Use lO.FNA to find the File Identifier of the file in the 
directory. 

• Access the file with lO.ACR, lO.ACW, or 10. ACE. 



C.6.3 Closing a File 
To close a file: 

• Deaccess the file with lO.DAC. 

C.fi.4 Extending a File 
To extend a file: 

• Use lO.FNA to find the file identifier if the file is not 
accessed . 

• Use 10. EXT to extend the file. 

C.6.5 Deleting a File 
To delete a file: 

• Use lO.FNA to find the file identifier. 

• Use lO.RNA to remove the directory name. 

• Use 10. DEL to delete the file. 

C.7 ERRORS RETURNED BY THE FILE PROCESSORS 

The error codes returned by FllACP and MTAACP are shown in Table C-2. 
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Table C-2 
File Processor Error Codes 



Error 
Code 



Operations 



Explanation 



I E.ABO 



lE.ALC 



lO.RVB/IO.WVB 



Extend or create operation 



lE.ALN 



IE. BAD 



lE.BDR 



lE.BHD 



lE.BVR 



An attempt to access a file 



Any function 



Directory operations 



Any operation 



Directory operations 



Indicates that all 

requested data was not 

transferred by the 
device . 

Indicates that the 
operation failed to 
allocate the file based 
on placement control or 
because of other related 
problems. 

Indicates that a file is 
already accessed on that 
LUN. 

Indicates that a required 
parameter is missing, 
that a parameter that 
must not be present is 
present, that a parameter 
that must be disabled is 
enabled, or that a 
parameter value is 
invalid. 

Indicates that you 
attempted a directory 
operation on a file that 
is not a directory, or 
that the specified 
directory is corrupted. 
This is usually caused by 
a version number field. 

Indicates that a corrupt 
file header was 
encountered, or that the 
operation required a 
feature not supported by 
the FCP (such as 
multiheader support or 
support for unimplemented 
features) . 

Indicates that you 
attempted to enter a name 
in a directory with a 
negative or version 
number . 



(continued on next page) 



C-13 



QIO INTERFACE TO THE ACPS 



Table C-2 (Cont.) 
File Processor Error Codes 



Error 
Code 



Operations 



Explanation 



IE, BYT 



Any function 



lE.BTP 



lE.CKS 



Unlabeled Magtape Create 



Any operation 



lE.CLO File access operations 



lE.DFU 



lE.DUP 



IE. EOF 



lE.HFU 



An allocation request 



An enter name operation 



lO.RVB/IO.WVB/IO.DEL 



An extended operation 



Retuiriea Dy exec 



This error is returned if 
the buffer specified is 
on an odd byte boundary 
or is not a multiple of 
four bytes. 

An attempt was made to 
create an unlabeled tape 
file with a record type 
other than fixed. 

Indicates that the 
checksum of a file header 
is incorrect. 

Indicates that the file 
was locked against access 
by the "deaccess lock 
bit." 

Indicates that there is 
insufficient free disk 
space for the requested 
allocation. 

Indicates that the name 
and version already 
exist. 

On read operations, this 
indicates an attempt to 
read beyond end of file. 
On truncate operations, 
it indicates an attempt 
to truncate a file to a 
length longer than that 
allocated or that the 
file was already at EOF. 

Indicates that the file 
header is full and cannot 
contain any more 
retrieval pointers and 
that adding an extension 
header is not allowed. 
When this is returned on 
a create operation, it 
indicates that the index 
file could not be 
extended to allow a file 
header to be allocated. 



TIT ,_T jr t- -i ^^ 3, 



(continued on next page) 
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Table C-2 (Cont.) 
File Processor Error Codes 



Error 






Code 


Operations 


Explanation 


lE.IFU 


Create or extend operation 


Indicates that there are 
no file headers available 
based on the param-eters 
specified when the volume 
was initialized. 


lE.LCK 


Returned on file access. 


Indicates that the file 




directory operations, and 


is already accessed by a 




on truncate 


writer and that shared 
write has not been 
requested or is not 
allowed . 


lE.LUN 


Any operation requiring 


Indicates that file ID 




a file ID 


has not been supplied and 
that the file is not 
accessed on the LUN. 


IE. NOD 


All file operations 


Indicates that an I/O 




that require DSR 


request failed due to 
lE.UPN, that the FCP was 
unable to allocate 
required space from DSR 
or from secondary pool 
for data structures. 


lE.NSF 


All file operations 


Indicates that the 
specified directory entry 
does not exist, that a 
file corresponding to the 
file ID does not exist, 
or that the file is 
marked for delete. 


lE.OFL 


Returned by exec 


The device is off line. 


lE.PRI 


Any operation 


Indicates that the user 
does not have the 
required privilege for 
the requested operation, 
or that the user has not 
requested the proper 
access to the file if the 
file is already accessed 
(for example, an attempt 
to write to a file that 
is accessed for read) . 
This also indicates an 
attempt to do file I/O to 
a device that is not 
mounted. 



(continued on next page) 
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Table C-2 (Cont.) 
File Processor Error Codes 



Error 






Code 


Operations 


Explanation 


lE.RER 


Any operation 


Indicates that the FCP 
encountered a fatal 
device read error during 
an operation; the 
operation has been 
aborted. 


lE.SNC 


Any operation 


Indicates that the file 
number and the value 
contained in the header 






do not agree. This 
generally means that the 
header has gone bad due 
to a crash or a hardware 
error. 


lE.SPC 


Returned by exec 


Indicates an illegal 
buffer. 


lE.SQC 


Any operation 


Indicates that the file 
sequence number does not 
agree with the file 
header; usually 
indicates that the file 
has been deleted and the 
header has been reused. 


lE.WAC 


File access operations 


Indicates that the file 
is already write accessed 
and lock against writers 
is requested. 


IE. WAT 


Write attributes 


Indicates that the FCP 




and deaccess 


encountered an invalid 
attribute. 


lE.WER 


Any operation 


Indicates that the FCP 
encountered a fatal 
device write error during 
an operation. The 
operation has been 
aborted but the disk 
structure. may have been 
corrupted. 


lE.WLK 


Any operation 


Indicates that the volume 




requiring write access 


is software write-locked . 
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ADOl-D, 14-1 
AFCll, 14-1 
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14-3 

FORTRAN interface, 14-3 to 
14-7 

standard QIO, 14-2 

status return, 14-8 to 14-9 
A/D gain range, 14-10 
AAll-K, 22-2 
AAVll-K, 22-2 
ACP 

QIO interface, C-1 
ADOl-D, 14-1 
ADll-K, 22-2 
ADVll-K, 22-2 
AFCll, 14-1 
AMll-K, 22-2 
Ana log- to- digital converter 

See A/D converter 
Ancillary Control Processor 

See ACP 
ARll, 16-1 to 16-2 
ASR-33, 2-3, 3-2 
ASR-3 5, 2-3, 3-2 
Assign LUN 
AST 

service routine, 1-11, 1-13 

terminating service, 1-24 

unsolicited- input-character, 
3-32 to 3-33 
ASTX$S, 1-24 

Asynchronous serial line 
interface 

DLll, 2-40, 3-30 

DLll-E, 12-2 
Asynchronous serial line 
multiplexer 

DHll, 2-40, 3-29 

DHVll, 2-40 

DJll, 2-40, 3-30 

DZll, 2-40, 3-30 
Asynchronous System Trap 

See AST 
Auto-baud speed detection, 2-42 
Automatic carriage return, 2-34, 
3-27 to 3-28 

Badge reader, 2-4A, 3-3 
Block size 

magnetic tape, 8-14 
Break-through" write, 2-22 
Buffer 

type-ahead, 2-37 



Buffering 

variable-length, 3-28 



v^aru input error 



error recovery, 11-3 
Card reader, 11-1 

binary format, 11-9 

control character, 11-8 

data format, 11-9 

data format translation, 11-9 

device-specific QIO, 11-3 

format translation, 11-10 

indicator light 

list of, 11-5 to 11-6 

standard QIO, 11-2 

switch 

list of, 11-5 to 11-6 
Card reader check 

recovery, 11-4 
Carriage return 

automatic, 2-34, 3-27 to 3-28 
Cassette, 9-1 

block length, 9-8 

device-specific QIO, 9-3 

space functions, 9-7 

standard QIO, 9-2 

status return, 9-3 to 9-5 

structure, 9-6 
Character 

control, 2-27, 2-33 

task-buffering of received, 
2-36 

vertical format control, 2-34, 
10-6 
Checkpointing 

during terminal input, 3-31 
Control character 

card reader, 11-8 
list of, 11-9 

terminal, 2-27, 2-33, 3-20, 
3-25 
Controller 

DECtape, 6-1 

disk 

UDA50, 5-4 
Counter 

initial value, 18-23 to 18-24 

interrupt 

disconnect, 18-23 to 18-24 
CRll, 11-1 
CTRL/C, 3-20 
CTRL/I, 3-20 
CTRL/J, 3-20 
CTRL/K, 3-20 
CTRL/L, 3-20 
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CTRL/M, 3-20 

CTRL/0, 2-13, 3-21 

CTRL/Q, 3-21 

CTRL/R, 3-21 

CTRL/S, 3-21 

CTRL/U, 3-21 

CTRL/Z, 3-21 

Cursor control, 2-39, 3-33 

Data format 

card reader, 11-9 
DECprinter, 2-4 

LA180, 10-2 
DECtape, 6-1 

device-specific QIO, 6-3 
recovery procedure, 6-6 
reversing direction, 6-7 
select recovery, 6-7 
standard QIO, 6-2 
status return, 6-4 to 6-6 
DECTAPE II 
See TU58 
Density selection 

magnetic tape, 8-15 
Device 

attaching to, 1-26 
detaching, 1-27 
logical, 1-18 
null, 19-1 
Device name 

physical, 1-18 to 1-20 
DHll, 2-40, 3-29 

remote, 3-31 
Diagnostic function 

user-mode, 1-30 
Dial-up line, 2-42 
Digital output 
bistable 

multipoint, 18-18 
multipoint, 18-17 
DIR$ macro, 1-16 
Directive Parameter Block 

See DPB 
Disk 

cartridge 
RK05, 5-3 
RK06, 5-3 
RK07, 5-3 
RL02, 5-3 
emulator 

ML-11, 5-4 
fixed 

RA80, 5-4 
RA81, 5-4 
RD51, 5-4A 
fixed-head 

RFll/RSll, 5-1 
RS03, 5-1 
RS04 , 5-1 
fixed/removable 

RC25, 5-4A 
flexible 
RXOl, 5-4 



Disk 

flexible (Cont.) 
RX02, 5-4 
RX50, 5-4A 
geometry, 5-2 
last- track, 5-12 
pack 

RA60, 5-4 
RM02, 5-3 
RM03, 5-3 
RM05, 5-3 
RM80, 5-3 
RP02, 5-1 
RP03, 5-1 
RP04, 5-3 
RP05, 5-3 
RP06, 5-3 
power-fail recovery, 1-39 
removable/fixed 

RC25, 5 -4 A 
status return, 5-8 to 5-11 
Disk controller 

UDA50, 5-4 
DJll, 2-40, 3-30 
DLll, 2-40, 3-30 

receiver interrupt enable, 
3-33 
DMCll, 12-3 
DPll, 12-3 
DPB, 1-13 

diagnostic, 1-31 
previously defined, 1-16 
QIO, 1-14 
DQll, 12-3 
DRll-K, 22-2 
DRVll, 22-2 
DSS/DRS 

configuration, 18-7 
DSSll, 18-1 

address assignment, 18-2 
DT07, 23-1 

device-specifc QIO, 23-4 to 

23-6 
FORTRAN interface, 23-8 
power-fail recovery, 23-6 
standard QIO, 23-2 to 23-3 
status return, 23-7 
DUll, 12-3 
DUPll, 12-4 
DZll, 2-40, 3-30 

remote, 3-31 to 3-32 

End-of-tape 

logical, 9-8 

paper tape, 17-5 
End-of-volume status 

magnetic tape, 8-15 to 8-16 
Escape code 

conversion, 2-40A, 3-30 
Escape sequence, 2-29, 3-22 

receiving, 2-32 

syntax exception, 2-33, 3-26 

syntax violation, 2-32, 3-24 



[ndex- 



INDEX 



Escape sequence (Cont.) 

VTIOO, 2-31 
Event 

significant, 1-12 
Event flag 

wait for, 1-24 

Fixed and removable, single 
spindle disk, 5-4A 

Format control 
vertical 

line printer, 10-5 to 10-6 
terminal, 3-26 to 3-27 

Gain 

A/D, 14-10 
Get Multiple Characteristics, 

2-13 
GLUN$, 1-21 

A/D converter, 14-2 

card reader, 11-1 to 11-2 

cassette, 9-1 to 9-2 

DECtape, 6-1 to 6-2 

disk, 5-4A 

DT07 UNIBUS switch, 23-2 

full-duplex terminal driver, 

2-6 to 2-7 
graphic display driver, 20-1 
half-duplex terminal driver, 

3-4 to 3-5 
ICS/ICR, 18-8 
laboratory peripheral system, 

16-2 
line printer, 10-2 to 10-3 
LPAll-K, 21-2 
magnetic tape, 8-3 
message-oriented 

communication device, 

12-4 
paper tape, 17-1 
PCL, 13-2 
table of bits returned, 1-22 

to 1-23 
TU58, 7-1 to 7-2 
UDCll, 15-3 
virtual terminal, 4-1 
Graphic display driver 

device-specific QIO, 20-2 
standard QIO, 20-2 
status return, 20-3 

Hard receive error 
detection, 2-36 



I/O 

canceling request, 1-27 
completion, 1-32 
function code 

summary, B-1 
issuing request, 1-16 
logical, 1-2 
physical, 1-2 



I/O (Cont.) 

standard function, 1-25 to 

1-26 
status block, 1-11, 1-35 
status code, 1-33 

summary, B-1 
status condition 

table, 1-36 to 1-38 
virtual, 1-2 
I/O status block 
K-series, 22-32 
LPAll-K, 21-30 to 21-32 
ICS/ICR, 18-1 

address assignment, 18-2 
configuration, 18-7 
device-specific QIO, 18-8 to 

18-12 
direct access, 18-75 to 18-80 
error recovery, 18-71 
FORTRAN interface, 18-35 to 

18-70 
list of supported module, 

18-3 
standard QIO, 18-8 to 18-12 
Industrial control subsystem, 

18-1 
Interface 

terminal, 3-2 
Interrupt 
counter 

disconnect, 18-23 to 18-24 
link task to, 18-27 
digital 

connect, 18-20 to 18-21 
disconnect, 18-21 to 18-23 
link task to, 18-26 
error 

link task to, 18-28 
terminal 

connect, 18-24 
link task to, 18-28 
unsolicited 

activating task, 18-25 
ICS/ICR processing, 18-18 
to 18-20 

K-series, 22-1 

buffer management, 22-32 

FORTRAN interface, 22-7 to 
22-30 

I/O status block, 22-32 

MACRO-11 interface, 22-31 

routine 

generating, 22-4 to 22-5 
Key 

escape, 3-22 

return, 3-22 

rubout, 3-22, 3-24 

special, 2-29 
KSR-33, 2-3, 3-2 
KSR-35, 2-3, 3-2 
KWll-K, 22-3 
KWVll-A, 22-3 



Index-3 



INDEX 



LAIOO, 2-3 
LAI 2, 2-3 
LA120, 2-4, 3-3 
LA180, 10-2 
LA180S, 2-4, 3-3 
LA30, 2-4, 3-2 
LA30-P, 3-29 
LA34, 2-4 
LA36, 2-4, 3-2 
LA38, 2-4 
LA50, 2-4A 
Laboratory peripheral 

K-series support routine, 
22-1 
Laboratory Peripheral 
Accelerator 
See LPAll-K 
Laboratory peripheral system, 
16-1 
clock rate, 16-33 to 16-34 
device-specific QIO, 16-3 to 

16-9 
FORTRAN interface, 16-9 
subroutine summary, 16-11 

to 16-28 
synchronous subroutine, 
16-10 
sampling rate, 16-33 to 16-34 
standard QIO, 16-2 
status return, 16-29 to 16-33 
Laser printer 

LNOl, 10-2 
Letter-Quality Printer, 2-4 
Line 

remote, 2-41 to 2-42, 3-31 to 
3-32 
Line printer 
list of, 10-1 
LPll, 10-2 
LSll, 10-2 
LVll, 10-2 

ready recovery, 10-5 
status return, 10-4 to 10-5 
LNOl, 10-2 
Logical block 
reading, 1-28 
writing, 1-29 
Logical device, 1-18 
Logical end-of-tape, 9-8 
Logical I/O, 1-2 
Logical unit number, 1-6, 1-17 
changing assignment, 1-7 
retrieving, 1-21 
Logical unit table, 1-6 
LPll, 10-2 
LPAll-K, 21-1 

22-bit addressing, 21-36 
buffer management, 21-32 to 

21-33 
device-specific QIO, 21-27 to 

21-29 
FORTRAN interface, 21-2 to 
21-27 



LPAll-K (Cont.) 

I/O status block, 21-30 to 
21-32 

microcode, 21-34 to 21-35 

time-out, 21-35 

unloading driver, 21-35 
LPSll, 16-1 to 16-2 
LQP02, 2-4 
LSll, 10-2 
LVll, 10-2 

Magnetic tape, 8-1 

density selection, 8-15 

device-specific QIO, 8-4 to 
8-9 

list of, 8-2 

select recovery, 8-13 

standard QIO, 8-4 

status return, 8-10 to 8-12 
.MCALL directive, 1-17 
Message traffic 

low, 12-12 
Message-oriented communication 

device-specific QIO, 12-5 to 
12-7 

full-duplex, 12-11 

half-duplex, 12-11 

redundancy checking, 12-11 

standard QIO, 12-5 

status return, 12-8 to 12-10 

transmission validation, 
12-11 
Message-oriented communication 

driver, 12-1 
ML-11, 5-4 
Modem, 2-42, 3-32 
Multiplexer 

asynchronous serial line, 
2-40, 3-29 to 3-30 

Q BUS, 2-40 

Null device, 19-1 
Overlapped seek, 5-7 

Paper tape 

error conditions, 17-4 

punch, 17-1 

reader, 17-1 

ready recovery, 17-4 

standard QIO, 17-2 

status return, 17-3 to 17-4 
Parallel Communications Link 

See PCL 
Parallel interface 

DAll-B, 12-2 

receiver 

device-specifc QIO, 13-9 to 

13-11 
standard QIO, 13-8 
status return, 13-11 to 

13-12 
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PCL ( Cont . ) 

transmitter 

device-specifc QIO, 13-3 to 

13-5 
standard QIO, 13-3 
status return, 13-6 to 13-8 
PCLll 

See PCL 
PCLll-B, 13-1 
Personal Printer, 2-4A 
Physical device name, 1-18 to 

1-20 
Physical I/O, 1-2 
Power-fail recovery, 1-39 

card reader, 11-4 

DMCll, 12-12 

DT07, 23-6 

ICS/ICR, 18-72 

line printer, 10-5 

magnetic tape, 8-14 
Print line truncation, 10-7 
Printer 

LA180, 10-2 

LNOl, 10-2 

LPll, 10-2 

LSll, 10-2 

LVll, 10-2 
Process control 

asynchronous, 14-3, 15-16 

synchronous, 14-3, 15-16 
Pseudo-device 

name, 1-21 
Punched card, 11-1 

QIO, 1-16 

$C form, 1-15 
device-independent, C-1 
device-specific 

A/D converter, 14-2 to 14-3 
card reader, 11-3 
cassette, 9-3 
DECtape, 6-3 
disk, 5-7 to 5-8 
DT07, 23-4 to 23-6 
graphic display driver, 

20-2 
ICS/ICR, 18-8 to 18-12 
laboratory peripheral 

system, 16-3 to 16-9 
LPAll-K, 21-27 to 21-29 
magnetic tape, 8-4 to 8-9 
message- oriented 

communication, 12-5 to 

12-7 
PCL receiver, 13-9 to 13-11 
PCL transmitter, 13-3 to 

13-5 
RA80, 5-8 
terminal, 2-8 to 2-10, 3-5 

to 3-6 
TU58, 7-3 to 7-4 
UDCll, 15-3 to 15-9 
virtual terminal, 4-2, 4-5 



QIO (Cont.) 
$ form, 1-14 
function summary, A-1 
macro format, 1-9 
$S form, 1-15 
standard 

A/D converter, 14-2 
card reader, 11-2 
cassette, 9-2 
DECtape, 6-2 
disk, 5-5 to 5-7 
DT07, 23-2 to 23-3 
graphic display driver, 

20-2 
ICS/ICR, 18-8 to 18-12 
laboratory peripheral 

system, 16-2 
line printer, 10-3 
magnetic tape, 8-4 
message- oriented 

communication, 12-5 
paper tape, 17-2 
PCL receiver, 13-8 
PCL transmitter, 13-3 
terminal, 2-7 
TU58, 7-2 to 7-3 
UDCll, 15-3 
summary of form, 1-14 
virtual terminal, 4-2 
QIOW$, 1-16 
Queue I/O and Wait 

See QIOW$ 
Queue I/O Request 
See QIO 

RA60, 5-4 
RA8 0, 5-4 
RA81, 5-4 
RC25, 5-4A 
RD51, 5-4A 
Ready recovery 

card reader, 11-4 

paper tape, 17-4 
Receive error 

hard, 2-36 
Remote line, 2-41 to 2-42 

answer speed, 2-42 

disconnecting, 2-23 
Removable and fixed, single 

spindle disk, 5-4A 
RFll/RSll, 5-1 
RK05, 5-3 
RK06, 5-3 
RK07, 5-3 
RL02, 5-3 
RM02, 5-3 
RM03, 5-3 
RM05, 5-3 
RM80, 5-3 
RP03, 5-1 
RP04, 5-1, 5-3 
RP05, 5-3 
RP06, 5-3 
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RS03, 5-1 
RS04, 5-1 
RT02, 2-4A, 3-3 
RT02-C, 3-3 

control function, 2-40A, 3-30 
RUBOUT, 3-24 

line printer, 10-6 
RXOl, 5-4 
RX02, 5-4 
RX50, 5-4A 

Seek 

overlapped, 5-7 
Select recovery 

magnetic tape, 8-13 
Significant event, 1-12 
Speed detection 

auto-baud, 2-42 
SST, 1-12 
Status block 

I/O, 1-35 
Status code 

I/O, 1-33, B-1 
Status return 

A/D converter, 14-8 to 14-9 

card reader, 11-3, 11-7 

cassette, 9-3 to 9-5 

DECtape, 6-4 to 6-6 

disk, 5-8 to 5-11 

DT07, 23-7 

graphic display driver, 20-3 

ICS/ICR, 18-13 to 18-14 

laboratory peripheral system, 
16-29 to 16-33 

line printer, 10-4 to 10-5 

magnetic tape, 8-10 to 8-12 

message-or iented 

communication, 12-8 to 
12-10 

paper tape, 17-3 to 17-4 

PCL receiver, 13-11 to 13-12 

PCL transmitter, 13-6 to 13-8 

terminal, 2-23 to 2-27 

TU58, 7-4 to 7-5 

UDC, 15-32 to 15-34 
Synchronous line interface 

DMCll, 12-3 

DPll, 12-3 

DQll, 12-3 

DUll, 12-3 

DUPll, 12-4 
Synchronous System Trap 

See SST 



TAll, 9-1 

TCll-G, 6-1 

Teletype, 2-3, 3-2 

Terminal 

attaching, 2-12 to 2-13 
control character, 2-27 to 

2-29 
desk-top, 2-3 



Terminal (Cont.) 

device-specific QIO, 2-8, 3-5 
to 3-6, 3-8 

escape sequence, 2-29 

escape sequence recognition, 
2-13 

full-duplex, 2-14 

full-duplex operation, 2-38 

graphics, 2-5 

half-duplex, 3-1 

interface, 2-39 

portable, 2-3 

QIO subfunction bit, 2-9 

special key, 2-30 to 2-31 

standard interfaces, 3-2 

standard QIO function, 2-7 

status return, 2-23 to 2-27 

subfunction, 3-7, 3-9 

subfunction summary, 2-11 

teletype, 2-3 

type, 2-17 

virtual, 4-1 
Terminal characteristics, 2-13 
to 2-15 

setting, 2-21 

side effects, 2-41, 3-32 

virtual terminal, 4-6 
Terminal driver 

loadable, 3-33 

virtual, 4-1 
Terminal line truncation, 3-30 
Trap 

system, 1-12 
Truncation 

print line, 10-7 

terminal line, 3-30 
TU58, 7-1 
Type-ahead, 2-37 

UDA50, 5-4 
UDC, 15-1 

device-specific QIO, 15-3 to 
15-9 

direct access, 15-10 

FORTRAN interface, 15-15 

FORTRAN subroutine summary, 
15-17 to 15-31 

standard QIO, 15-3 

status return, 15-32 to 15-34 
UDCll, 15-1, 18-3 
UMDIO$, 1-31 
UNIBUS 

power-fail recovery, 23-6 
UNIBUS' switch, 23-1 
Universal digital controller 

See UDC 
Unlabeled tape, 8-15 to 8-16 
User-mode diagnostic function, 
1-30 

Vertical format control 

line printer, 10-5 to 10-6 
terminal, 2-33, 3-26 to 3-27 
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Virtual block VT105, 2-6 

reading, 1-28 VTll, 20-1 

writing, 1-29 VT131, 2-6 

Virtual I/O, 1-2 VT50, 2-5, 3-3 

Virtual terminal, 4-1 VT50H, 2-5, 3-3 

device-specific QIO, 4-2, 4-5 VT52, 2-5, 3-4 

VS60, 20-1 VT55, 2-5, 3-4 

VT05B, 2-5, 3-3 VT61, 2-5, 3-4 
VTIOO, 2-5, 3-4 

escape sequence format, 2-31 Write 

VTlOl, 2-6 break-through, 2-22 

VT102, 2-6 WTSE$, 1-24 
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READER'S COMMENTS 



NOTE: This form is for document comments only. DIGITAL will use comments submitted on this form at the 
company's discretion. If you require a written reply and are eligible to receive one under Software 
Performance Report (SPR) service, submit your comments on an SPR form. 
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n Higher-level language programmer 
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D User with little programming experience 

□ Student programmer 
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Name _ Date . 

Organization 

Street 



City — State Zip Code _ 

or Country 



— — — Do Not Tear - Fold Here and Tape 



mmm 



No Postage 

Necessary 

if Mailed in the 

United States 



BUSINESS REPLY MAIL 

FIRST CLASS PERMIT N0.33 MAYNARD MASS. 



POSTAGE WILL BE PAID BY ADDRESSEE 



BSSG PUBLICATIONS ZK1-3/J35 
DIGITAL EQUIPMENT CORPORATION 
110 SPIT BROOK ROAD 
NASHUA. NEW HAMPSHIRE 03061 




— — — Do Not Tear - Fold Here 



.S 

T3 
S 

o 
O 
an 

s 
o 



a 
u 



